Awkl

Awk's well-kempt library

Table of Contents

• 📰 Description
• 📦 Modules
• 📟 Usage
• 📓 API reference
• 🚀 Installation
• 📝 Licence

📰 Description

Awkl (short for Awk's well-kempt library) is a library that attempts to bring modules present in other languages' standard libraries to gawk

The library makes use of gawk's namespaces (available since version 5.0) and other gawk-specific features, but we reckon a good part of the library could be adapted to be awk-agnostic (maybe with a hypothetical transpiler)

📦 Modules

• math: Math-related functions
• str: String-related functions
• arr: Array-related functions
• stats: Statistics-related functions
• rnd: Randomness-related functions
• path: Filesystem paths-related functions
• type: Type-related functions
• time: Timing-related functions
• cmd: System commands related functions
• opt: Command-line argument parser
• bit: Functions for bit manipulation
• color: Functions for coloring text in Xterm terminals
• set: Functions for sets
• parseutils: Functions to help parsing strings
• test: Unit tester
• bench: Benchmarker

📟 Usage

Ensure your AWKPATH includes the /usr/share/awk path (or ~/.local/share/awk in case of user-installation):

export AWKPATH="$AWKPATH:/usr/share/awk"

And now you can include the modules:

• On the command-line with the -i option:

gawk -i math 'BEGIN { print math::sec(math::pi) }'
gawk -i rnd 'BEGIN { print rnd::randString() }'
gawk -i str '{ print str::trim(0ドル) }' <<EOF
	one 
	two 
EOF

• On scripts with the @include directive:

#!/usr/bin/env -S gawk -E
@include "math"
@include "stats"
BEGIN {
	print math::hypot(3,4)
	A[1] = 10
	A[2] = 20
	print stats::mean(A)
}

📓 API reference

The API reference can be generated with doxygen from comments in the source code. Run from the project's root directory:

make docs-style
make docs

We provide our awkxygen script as an executable so you can also generate API references for your own awk libraries by configuring your Doxyfile like so:

FILE_PATTERNS = *.awk
EXTENSION_MAPPING = awk=c++
INPUT_FILTER = awkxygen

and run doxygen.

The script depends on this library. If it's not installed but you have the source code you can still do:

PATH="$PATH:/path/to/awkl/bin" AWKPATH="/path/to/awkl/src" doxygen

🚀 Installation

git clone --filter=blob:none https://codeberg.org/tplasdio/awkl.git
cd awkl
autoreconf -i
./configure # For system-installation
#./configure --prefix ~/.local # For user-installation
sudo make install

curl -O https://codeberg.org/tplasdio/awkl/raw/branch/main/packaging/PKGBUILD-git
makepkg -sip PKGBUILD-git

curl -O https://codeberg.org/tplasdio/awkl/raw/branch/main/packaging/lure-git.sh
lure build -s lure-git.sh

📝 Licence

GPL-3.0-or-later