awk-polycall

AWK binding for libpolycall 1.5.0, published as @obinexusltd/awk-polycall.

Portable AWK has no standard in-process C FFI, so this package uses a strict two-layer adapter:

1. awk_polycall.awk invokes a small native host with system().
2. awk-polycall-host calls polycall_ffi_run_config(config_path, 1).

The configuration path is passed through the child environment, avoiding command-line parsing and quoting. No layer parses configuration or duplicates libpolycall runtime logic.

Install from npm

npm install @obinexusltd/awk-polycall

The CommonJS entry point exposes absolute paths for native and AWK tooling:

const polycall = require('@obinexusltd/awk-polycall');

console.log(polycall.awk);
console.log(polycall.nativeAdapter);
console.log(polycall.hostSource);
console.log(polycall.publicHeader);
console.log(polycall.ffiHeader);
console.log(polycall.config);

The npm package contains all AWK/C sources, public and generated headers, examples, tests, scripts, the Makefile, manifest, and runtime configuration. Compiled host binaries are platform-specific and therefore excluded.

AWK API

Load the adapter before your AWK program:

BEGIN {
    status = polycall_run_config("awk-polycallrc")
    if (status != 0) {
        exit status
    }
}

For startup paths where failure should immediately terminate AWK:

BEGIN {
    polycall_run_or_exit("awk-polycallrc")
}

If awk-polycall-host is not on PATH, set its command with -v:

awk -v polycall_host=/path/to/awk-polycall-host \
  -f node_modules/@obinexusltd/awk-polycall/src/awk_polycall.awk \
  -f application.awk

polycall_run_config returns the host process status. Portable process exit codes are limited to 0–255; the native C adapter still preserves the full libpolycall integer status before the host converts it for AWK.

Build and test

Build the native adapter archive and run its tests:

npm run build
npm test
npm run verify

npm test automatically searches for awk, gawk, or mawk; on Windows it also checks common Git and MSYS installation paths. The AWK smoke test reports an explicit skip when no interpreter is available, while native and npm tests still run.

Build the real host

Link against a libpolycall v1.5 library exporting polycall_ffi_run_config:

make host POLYCALL_LDFLAGS="-L/path/to/libpolycall/lib -lpolycall"

Then run the included example:

awk -v polycall_host=bin/awk-polycall-host \
  -f src/awk_polycall.awk \
  -f examples/basic.awk

The read-only shared-schema override is awk-polycallrc.

Publishing

Inspect the package and publish the public npm scope:

npm pack --dry-run
npm publish --access public

Publishing is not performed automatically.

Author

Nnamdi Michael Okpala — [email protected]