wip: large changes

t/INSTALL.x

@@ -0,0 +1,55 @@
+Format_Index: y, a
+Installation Instructions
+*************************
+
+Copyright (C) %d %s
+
+   Copying and distribution of this file, with or without modification,
+are permitted in any medium without royalty provided the copyright
+notice and this notice are preserved.  This file is offered as-is,
+without warranty of any kind.
+
+Basic Installation
+==================
+
+   Briefly, the shell command `./configure && make && make install` should
+configure, build, and install this package. The following more-detailed
+instruction are generic; see the `README` file for instructions specific to
+this package.
+
+   The `configure` shell script attempts to guess correct values for
+various system-dependent variables used during compilation. It uses
+those values within a `Makefile` to build for that POSIX system as
+defined by `config.mak` which was generated by `configure`.
+
+Compilers and Options
+=====================
+
+  Some systems require unusal options for compilation or linking that
+the `configure` script does not know about. If you run into an issue
+run `./configure --help` to figure out what you can do to fix the
+behavoir.
+
+Installation Names
+==================
+
+  By default, `make install` installs the package's command under
+`/usr/local/bin`. You can specify an installation prefix other than `/usr/local/`
+by giving `configure` the option `--prefix=PREFIX` to `configure`, the package uses
+PREFIX as the prefix for installation programs and libraries.
+Documentation and other data files still use the regular prefix.
+
+`configure` Invokation
+======================
+
+  `configure` recongizes the following options to control its operations.
+
+  `--help`
+     Prints a summary of all the options to `configure`, and exits.
+  `--prefix=PREFIX`
+     Sets the installation prefix.
+  `CFLAGS`
+    Sets the flags used during compilation.
+
+`configure` also accepts some other options. Run `configure --help` for more
+details

t/Makefile.x

@@ -0,0 +1,64 @@
+	Format_Index: p
+# SPDX-License-Identifier: BSD-3-Clause
+PACKAGE := %s
+
+SRCS := $(wildcard src/*.c) $(wildcard lib/*.c)
+OBJS := $(patsubst src/%.c,build/obj/%.o,$(SRCS))
+
+BIN := bin/$(PACKAGE)
+
+COMMIT := $(shell git rev-list --count --all)
+FLAGS := -I. -DCOMMIT=$(COMMIT) --std=c2x -pedantic -Ibuild/include
+
+VERSION := $(shell git describe --tags --always --dirty)
+TARBALL := $(PACKAGE)-$(VERSION).tar.gz
+RELEASE_FILES := doc src lib COPYING AUTHORS README $(PACKAGE).1 INSTALL Makefile configure config.h
+
+-include config.mak
+
+ifeq ($(wildcard config.mak),)
+all:
+	@echo "File config.mak not found, run configure"
+	@exit 1
+else
+
+all: build $(BIN) doc
+
+build:
+	mkdir -p bin
+	mkdir -p build/obj
+
+build/obj/%.o: src/%.c config.mak
+	$(CC) $(FLAGS) $(CFLAGS) -c $< -o $@
+
+$(BIN): $(OBJS) 
+	$(CC) $(FLAGS) $(CFLAGS) $^ -o $@
+
+endif
+
+install: $(BIN)
+	cp $(BIN) $(PREFIX)
+
+doc:
+	$(MAKE) -C doc all
+
+uninstall:
+	$(RM) $(PREFIX)$(PACKAGE)
+
+clean:
+	$(RM) -r bin
+	$(RM) -r build
+	$(MAKE) -C doc clean
+
+distclean: clean
+	$(RM) config.mak config.status
+	$(RM) $(TARBALL)
+	$(MAKE) -C doc clean
+
+release: clean all
+	tar -czf $(TARBALL) $(RELEASE_FILES)
+
+test:
+	@$(BIN) --version > /dev/null 2>&1 && echo "intact"|| echo "defective"
+
+.PHONY: all clean distclean install uninstall build release doc

t/README-dev.x

@@ -0,0 +1,113 @@
+Format_Index: y, a
+This README.dev file describes the development environment.
+
+  Copyright (C) %d %s.
+
+  Copying and distribution of this file, with or without modification,
+  are permitted in any medium without royalty provided the copyright
+  notice and this notice are preserved.
+
+Notice
+------
+
+This documentation is standard across all GCK package and is not specified per
+package; however, this is the defacto standard for most packages. The only
+place where this commonly differs is in non-binary or library packages.
+
+
+Build system
+------------
+
+This distribution uses a GNU autotools-like build system. This is made up of a
+configure script, and a Makefile. The configure script detects a C23 compiler
+on the system and sets any program flags: debug, release, custom. The Makefile
+builds the binary based on the output [config.mak] of the configure script.
+
+
+Building
+--------
+
+To build this distribution you first must run the configure script. This
+outputs a config.mak file that will be used in the Make step. Then run make;
+this builds the objects into build/ and the binary into bin/.
+
+
+Configuration
+-------------
+
+The configuration script is used to generate a build intermediate step called
+the config.mak. This file is used by the Makefile to figure out C compiler to
+use, what CFLAGS and LDFLAGS to use, and where to install the binary if
+requested. By default these values are gcc, the release flag set, and
+/usr/local/. The configuration script supports the following flags that control
+CFLAGS: --enable-debug and CFLAGS="". By default, the script uses flags for a release
+build. Debug is for in-development programming and is the strictest when it
+comes to warnings and other compiler output. CFLAGS="" is for custom flag
+definition. For the development environment is it recommended to use the
+--debug flag. Some examples of how you can run the configure script:
+
+For default behavior:
+
+  ./configure
+
+For debug use:
+
+  ./configure --enable-debug
+
+For help text:
+
+  ./configure --help
+
+The help text is a more useage specific and up-to-date reference for
+the configure script.
+
+
+Makefile
+--------
+
+The GNU Makefile is used to build the final executable, clean up build
+artifacts, and install the program. It checks for the config.mak which is
+generated by the configure script. For a regular build, once you have the
+configure script with desired flags, run:
+
+  make
+
+This builds the executable to bin/ and build objects to build/
+
+
+Suggested enviroment setup
+--------------------------
+It is suggested that you run do the following things to prepare you environment
+for development. This is not a strict enforcement, but due to the project
+structure it is a good starting point.
+
+  git pull
+  ./tools/Cleanup
+  ./configure --enable-debug
+  ./build-aux/generate-artifacts
+  make test
+
+This is to ensure that you have the most up-to-date source code, and that there
+are no major problems with the source control version.
+
+The git pull is used to sync with the repository and prevent conflicts. The
+cleanup is to ensure their are no lingering build artifacts. The configure with
+debug enabled is for strict build flags and -ggdb. Bear is used to generated
+compile_commands.json for the clang suite of tooling. Finally, run the program
+to ensure the chain works.
+
+
+Pre-commit checks
+-----------------
+
+Before you commit to source control ensure that done the following:
+
+  * Run the cleanup scripts
+
+    ./tools/Cleanup
+
+  * Ensure that all changes were atomic
+
+  * If you compted a TODO list item check it off.
+
+  * Based on complexity, test the feature accordingly.

t/README-release.x

@@ -0,0 +1,33 @@
+Format_Index:
+Here are most of the steps before you make a release.
+
+* Start from a clean, up-to-date git driectory on "master":
+
+  make -k distclean || { ./configure && make distclean; }
+  git checkout master
+  git pull origin master
+
+* Ensure that the latest stable versions of make, sh, etc.
+are in your path. See the prerequisites list in README-dev
+for a compile list of tools.
+
+* Ensure that you have no uncommitted diffs. This should produce
+no output:
+
+  git diff
+
+* Ensure that you've pushed all changes that belong in the release:
+
+  git push origin master
+
+* Pre-release testing: ensure that the following command succeeds:
+
+  make check syntax-check distcheck
+
+Once all the builds and tests have passed,
+
+* Run the following to create release tarballs.
+
+  make release
+
+* Upload the tarball to the relavent distribtuion platform.

t/README.x

@@ -0,0 +1,30 @@
+Format_Index: a, p, p, d, y, a, a, p
+This is the README file for the %s %s distribution.
+%s %s
+
+  Copyright (C) %d %s.
+
+  Copying and distribution of this file, with or without modification,
+  are permitted in any medium without royalty provided the copyright
+  notice and this notice are preserved.
+
+See the files ./INSTALL* for building and installation instructions.
+
+Bug reports:
+ Please include enough information for the maintainers to reproduce the
+ problem. Generally speaking, that means:
+- the contents of any input files necessary to reproduce the bug
+  and command line invocations of the program(s) involved (crucial!).
+- a description of the problem and any samples of the erroneous output.
+- the version number of the program(s) involved (use --version).
+- hardware, operating system, and compiler versions (uname -a).
+- unusual options you gave to configure, if any (see config.mak).
+- anything else that you think would be helpful.
+
+See README-dev for information on the development environment -- any
+interested parties are welcome. If you're a programmer and wish to
+contribute, this should get you started. If you're not a programmer,
+your help in writing test cases, checking documentation against the
+implementation, etc., would still be very much appreciated.
+
+%s %s is free software. See the file COPYING for copying conditions.

t/shell.x

@@ -0,0 +1,32 @@
+Format_Index: l, y, a, d
+#!/bin/sh
+# SPDX-License-Identifier: %s
+me=$0
+scriptversion="1.0.0"
+
+version="$me $scriptversion
+
+Copyright (C) %d %s.
+This is free software; you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law."
+
+usage="\
+Usage: $me [OPTION]...
+%s
+
+Options:
+
+   --help     print this help and exit
+   --version  output version information"
+
+while test $# -gt 0; do
+  case $1 in
+    --help) echo "$usage"; exit 0;;
+    --version) echo "$version"; exit 0;;
+    -*)
+     echo "$0: Unknown option '$1'." >&2
+     echo "$0: Try '--help' for more information." >&2
+     exit 1;;
+  esac
+  shift
+done

t/t

@@ -0,0 +1,154 @@
+#!/bin/sh
+# SPDX-License-Identifier: BSD-3-Clause
+me=$0
+scriptversion="1.0.1"
+
+version="$me $scriptversion
+
+Copyright (C) 2025 GCK.
+This is free software; you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law."
+
+usage="\
+Usage: $me [OPTION]...
+Generate template headers
+
+Options:
+
+   --help     print this help and exit
+   --version  output version information"
+
+while test $# -gt 0; do
+  case $1 in
+    --help) echo "$usage"; exit 0;;
+    --version) echo "$version"; exit 0;;
+    -*)
+     echo "$0: Unknown option '$1'." >&2
+     echo "$0: Try '--help' for more information." >&2
+     exit 1;;
+  esac
+  shift
+done
+
+x_files=$(find . -maxdepth 1 -name "*.x" -type f | sort)
+
+if test -z "$x_files"; then
+  echo "$0: No .x files found in current directory." >&2
+  exit 1
+fi
+
+output_file="../build/include/template.h"
+mkdir -p ../build/include/
+
+first_template=true
+
+{
+  echo "/* DO NOT MODIFY THIS FILE! It was generated by t $scriptversion. */"
+  echo "#ifndef TEMPLATE_H"
+  echo "#define TEMPLATE_H"
+  
+  for input_file in $x_files; do
+    base_name=$(basename "$input_file" .x)
+    template_name=$(echo "$base_name" | tr '[:lower:]' '[:upper:]')
+
+    tmp_format=$(mktemp)
+    tmp_template=$(mktemp)
+    tmp_params=$(mktemp)
+
+    format_index=$(head -n 1 "$input_file")
+    if ! echo "$format_index" | grep -q "^Format_Index:"; then
+      echo "$0: '$input_file': Missing Format_Index line." >&2
+      rm -f "$tmp_format" "$tmp_template" "$tmp_params"
+      continue
+    fi
+    
+    if test "$first_template" = false; then
+      echo ""
+    fi
+    first_template=false
+
+    tmp_specs=$(mktemp)
+
+    echo "$format_index" | sed 's/Format_Index://' | tr ',' '\n' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' > "$tmp_params"
+
+    tail -n +2 "$input_file" | sed '/^$/d' > "$tmp_template"
+
+    param_names=""
+    while IFS= read -r param; do
+      param_names="$param_names $param"
+    done < "$tmp_params"
+
+    while IFS= read -r line; do
+      echo "$line" | grep -o '%[sdifgxXoucpeEaAn]' >> "$tmp_specs"
+    done < "$tmp_template"
+
+    echo "/*"
+    
+    param_idx=1
+    for param in $param_names; do
+      format_type=""
+      spec=$(sed -n "${param_idx}p" "$tmp_specs")
+      case "$spec" in
+        %s|%S) format_type="(s)" ;;
+        %d|%i|%u|%x|%X|%o) format_type="(d)" ;;
+        %f|%g|%e|%E|%a|%A) format_type="(f)" ;;
+        %c) format_type="(c)" ;;
+        %p) format_type="(p)" ;;
+        %n) format_type="(n)" ;;
+        *) format_type="(?)" ;;
+      esac
+      
+      case "$param" in
+        a) param="author" ;;
+        y) param="year" ;;
+        l) param="license" ;;
+        d) param="description" ;;
+        p) param="package" ;;
+      esac
+      
+      printf " * %-13s%s\n" "$param" "$format_type"
+      param_idx=$((param_idx + 1))
+    done
+    
+    echo " */"
+    echo "const char templ_${template_name}[] = \"\\"
+    
+    line_count=0
+    total_lines=$(wc -l < "$tmp_template")
+    while IFS= read -r line; do
+      line_count=$((line_count + 1))
+      escaped_line=$(echo "$line" | sed \
+        -e 's/\\\\/__BSLASH__/g' \
+        -e 's/\\"/__BQUOTE__/g' \
+        -e 's/\\n/__NEWLINE__/g' \
+        -e 's/\\t/__TAB__/g' \
+        -e 's/\\r/__RETURN__/g' \
+        -e 's/\\a/__ALERT__/g' \
+        -e 's/\\b/__BACKSPACE__/g' \
+        -e 's/\\f/__FORMFEED__/g' \
+        -e 's/\\v/__VTAB__/g' \
+        -e 's/\\0/__NULL__/g' \
+        -e 's/\\/\\\\/g' \
+        -e 's/"/\\"/g' \
+        -e 's/__BSLASH__/\\\\/g' \
+        -e 's/__BQUOTE__/\\"/g' \
+        -e 's/__NEWLINE__/\\n/g' \
+        -e 's/__TAB__/\\t/g' \
+        -e 's/__RETURN__/\\r/g' \
+        -e 's/__ALERT__/\\a/g' \
+        -e 's/__BACKSPACE__/\\b/g' \
+        -e 's/__FORMFEED__/\\f/g' \
+        -e 's/__VTAB__/\\v/g' \
+        -e 's/__NULL__/\\0/g')
+      if test $line_count -lt $total_lines; then
+        printf '%s\\n\\\n' "$escaped_line"
+      else
+        printf '%s";\n' "$escaped_line"
+      fi
+    done < "$tmp_template"
+    
+    rm -f "$tmp_format" "$tmp_template" "$tmp_params" "$tmp_specs"
+  done
+  
+  echo "#endif"
+} > "$output_file"