AWKRS(1)

NAME
awkrs - pattern-directed scanning and processing language (Rust awk with parallel records and Cranelift JIT)

SYNOPSIS
awkrs [OPTIONS] [-f progfile | -e program | program] [--] [file ...]

DESCRIPTION
awkrs runs pattern → action programs over input records like POSIX awk, GNU gawk, and mawk. The CLI accepts the union of POSIX, gawk, and mawk (-W) options. The execution engine is a Cranelift-JIT bytecode VM with a parallel record processor that activates automatically when the program is parallel-safe and -j selects more than one thread; otherwise execution is sequential.

The program text is taken from the first non-option argument unless -f or -e is given. Remaining non-option arguments are input files; if none are given, standard input is read.

OPTIONS

  POSIX

-f PROGFILE, --file=PROGFILE
    Read program source from PROGFILE. May be repeated; sources are concatenated.

-F FS, --field-separator=FS
    Set the input field separator (FS).

-v var=val, --assign=var=val
    Assign val to var before BEGIN runs. Repeatable.

  GNU program sources

-e PROGRAM, --source=PROGRAM
    Inline program text. Repeatable; sources are concatenated.

-i FILE, --include=FILE
    Include awk source file (gawk @include behavior). Repeatable.

  gawk extensions

-b, --characters-as-bytes
    Use byte length for length, substr, index.

-c, --traditional
    Traditional POSIX awk mode (stored on the runtime; minimal effect today).

-C, --copyright
    Print copyright information.

-d[FILE], --dump-variables[=FILE]
    Dump globals after the program runs. Argument is a path, -, or empty for stdout.

-D[FILE], --debug[=FILE]
    Static rule/function listing to FILE or stderr. Not gawk's interactive debugger.

-E FILE, --exec=FILE
    Execute program from FILE then exit (gawk -E).

-g, --gen-pot
    Generate gettext .pot output and exit before execution.

-I, --trace
    Trace execution.

-k, --csv
    CSV mode. Sets FS to comma and FPAT to handle quoted fields with escapes.

-l LIB, --load=LIB
    Load LIB.awk from AWKPATH (default .). Bundled gawk extension names (filefuncs, readdir, time, ...) are accepted as no-ops; arbitrary .so modules error at parse time.

-L LEVEL, --lint=LEVEL
    Lint level: fatal, invalid, no-ext. When the runtime variable LINT is truthy, additionally emits awkrs: warning: diagnostics on stderr for sqrt and log domain issues.

-M, --bignum
    Arbitrary-precision arithmetic via MPFR (rug, default 256 bits; PROCINFO["prec"]/PROCINFO["roundmode"] apply). Disables the JIT.

-N, --use-lc-numeric
    Apply LC_NUMERIC to sprintf/printf/print and %' grouping. String-to-number parsing for $n/$0 still uses ..

-n, --non-decimal-data
    Allow non-decimal input data (strtonum-style hex/octal coercion).

-o[FILE], --pretty-print[=FILE]
    Awkrs AST listing. Not gawk's canonical reformatter.

-O, --optimize
    Accepted for parity. The Cranelift JIT is on by default; use -s to disable.

-p[FILE], --profile[=FILE]
    Wall-clock summary plus per-record-rule hit counts (-j 1 only). Not gawk's per-line profiler.

-P, --posix
    Strict POSIX mode (stored on the runtime; minimal effect today).

-r, --re-interval
    Accepted as a no-op; {m,n} interval syntax is always enabled.

-s, --no-optimize
    Disable the Cranelift JIT.

-S, --sandbox
    Block system(), file redirects, pipes, coprocesses, and inet I/O.

-t, --lint-old
    Lint old-style awk constructs.

  mawk / BusyBox

-W OPT
    mawk-style option(s), comma-separated. help and usage print help and exit; version or v print the version; dump triggers a dump action. exec=FILE sets the exec file. Other tokens (posix_space, interactive, random, sprintf=N) are accepted silently for compatibility.

  awkrs-specific

-j N, --threads=N
    Worker threads for the parallel record engine. Default 1. The engine downgrades to sequential automatically when the program is not parallel-safe.

--read-ahead=N
    Lines per batch read from stdin in -j parallel mode without input files. Each batch is processed in parallel and printed in order before the next batch is read. Default 1024.

-h, --help
    Print the cyberpunk HUD help and exit.

-V, --version
    Print the version and exit.

PROGRAM TEXT
Program text follows POSIX awk and the gawk extensions documented in the project README. Highlights:

•   Rules: BEGIN, END, BEGINFILE, ENDFILE, empty pattern, /regex/, expression patterns, range patterns (/a/,/b/ or NR==1,NR==5). The four special patterns must use { ... }; record rules may omit braces for the default { print $0 }.

•   Statements: if, while, do-while, for (C-style and for (i in arr)), switch/case/default (gawk-style: no fall-through, regex case /re/), print/printf with >, >>, |, |& redirection, break, continue, next, nextfile, exit, delete, return, getline.

•   getline as expression returns 1 (read), 0 (EOF), -1 (error), -2 (gawk retryable I/O when PROCINFO[input,"RETRY"] is set).

•   Records and fields: RS is newline by default; one (UTF-8) char is a literal delimiter; RS="" is paragraph mode; multi-char is a gawk regex (RT holds the matched text). FIELDWIDTHS selects fixed-width when non-empty. FPAT selects pattern-based fields.

•   Namespaces and modules: @include, @load, @namespace.

•   Networking: /inet/tcp/..., /inet/udp/... endpoints for getline/print and the coprocess operator |&.

•   Introspection: PROCINFO, SYMTAB, FUNCTAB populated in gawk-compatible form (PROCINFO["sorted_in"] supports @ind_X, @val_X, and 2- or 4-arg user comparator functions).

ENVIRONMENT

AWKPATH
    Search path for -l and @include. Default ..

AWKLIBPATH
    Search path for @load.

GAWK_READ_TIMEOUT
    Default read timeout (ms) used as the fallback for PROCINFO[input,"READ_TIMEOUT"].

LC_NUMERIC
    Locale decimal radix and thousands grouping when -N is set; affects sprintf/printf/print output only, not $n/$0 parsing.

EXIT STATUS

0   Successful completion.

1   Error during program execution or invalid usage. Errors are written to stderr in the form awkrs: command: reason.

n   The program may exit with any status by calling exit n.

EXAMPLES
Print the second whitespace-separated field of every line:
    awkrs '{ print $2 }' input.txt

Sum a CSV column with quoted-field handling and four worker threads:
    awkrs -k -j 4 'NR>1 { s += $3 } END { print s }' data.csv

Run a program from a file, assign a variable, and read multiple inputs:
    awkrs -f report.awk -v threshold=100 a.log b.log

Disable the JIT (pure bytecode VM):
    awkrs -s '{ print NR, $0 }' big.txt

Wall-clock profile to a file (sequential mode required):
    awkrs -j 1 -p prof.out -f program.awk input.txt

Arbitrary-precision arithmetic:
    awkrs -M 'BEGIN { PREC=200; print 2^200 }'

FILES

completions/_awkrs
    Zsh completion. Add the directory to fpath and run autoload -Uz compinit && compinit.

PARITY GAPS
awkrs diverges from gawk in the following documented ways:

•   -D, -o, -p produce awkrs-specific output, not gawk's debugger / pretty-printer / per-line profiler formats.

•   -c, -P are accepted but currently have minimal runtime effect.

•   -r is a no-op; interval regex syntax is always available.

•   -N does not affect string-to-number parsing for $n/$0.

•   @load of arbitrary .so gawkapi modules is rejected; bundled extension names are accepted as no-ops because the builtins are native.

•   PROCINFO["platform"] returns gawk values (posix, mingw, vms), not Rust target names.

•   -M disables the Cranelift JIT.

•   JIT getline failures abort the JIT chunk instead of returning -1/-2; the VM path is fully gawk-compatible.

SEE ALSO
awk(1), gawk(1), mawk(1)

Project README, compatibility matrix, and benchmarks: github.com/MenkeTechnologies/awkrs (https://github.com/MenkeTechnologies/awkrs)

AUTHOR
Jacob Menke (MenkeTechnologies) <linux.dev25@gmail.com>.

BUGS
Report issues at github.com/MenkeTechnologies/awkrs/issues (https://github.com/MenkeTechnologies/awkrs/issues).