Testfile: make non-executable

CONDUCT

@@ -1,83 +0,0 @@
-Code of Conduct
-
-This Code of Conduct is derived from the 10 Pāramitās of Theravadin Buddhism.
-You can read more about them in Ṭhānissaro Bhikkhu’s Ten Perfections: A Study
-Guide [0].
-
-1. Generosity (Dāna)
-
-Give contributions freely and willingly under the terms of the GNU Affero
-General Public License, version 3 or later, or a compatible license.
-
-2. Ethics (Sīla)
-
-Do not use nonfree code or uncredited code in contributions. Do not contribute
-code of dubious origins, such as code generated by large language models or
-unlicensed snippets found online [1]. Do not take credit for others’
-contributions. Make sure to utilize the copyright header and license notice on
-source files to credit yourself and others for their work.
-
-3. Renunciation (Nekkhamma)
-
-Stay committed to the principles of simplicity and interoperability embodied by
-the project. Keep your personal will and desire out of the project, for it can
-only prove harmful to its success.
-
-4. Wisdom (Pañña)
-
-Look to established sources for standards, best practices, and important
-implementation details when setting new precedence. Follow the existing
-precedence where it applies.
-
-5. Energy (Viriya)
-
-Focus on the currently-open, currently-assigned, and currently-in-progress
-issues, pull requests, and other endeavors in order to keep yourself and others
-from being overwhelmed with responsibility, either from your zeal or your
-negligence.
-
-If you notice an issue, open an issue as soon as you can. If you see a neglected
-branch, open a pull request or comment on an existing one, if applicable. Be
-diligent in your commitment to making this project work.
-
-6. Patience (Khanti)
-
-Be patient with maintainers and other contributors. We all have our own lives
-going on and may need significant time to get to things.
-
-7. Truthfulness (Sacca)
-
-Communicate honestly and openly. Do not embellish facts to get your way. Make
-sure to let maintainers know about any issues along the way and keep ample
-communication channels open.
-
-8. Determination (Adhiṭṭhāna)
-
-Stay focused on long-term objectives and cultivate attainment to that
-achievement by utilizing to the fullest extent possible the tools available to
-you for managing the workload.
-
-9. Loving-Kindness (Mettā)
-
-Treat everyone with respect, even if they treat you poorly. This does not mean
-you have to put up with abuse, but make sure to respond with kindness and with
-love in your heart. Support and uplift maintainers and other contributors with
-your words and actions.
-
-Do not use angry or hateful language toward contributors, such as demeaning
-phrases and slurs. Make sure that if you do not know the pronouns of a
-contributor to ask for them and, in the meantime, use gender-neutral they/them
-or equivalent pronouns.
-
-10. Equanimity (Upekkhā)
-
-Keep a balanced perspective on all suggestions and contributions and make
-judgements not from a place of ego and personal preference but on their
-usefulness and suitability to the project. Make sure to keep an eye on the
-bigger picture as implementing individual features may seem intuitive at first
-but scale poorly in practical use. Keep a level head about your own work: it is
-not shameful to make a mistake in this vein, and fixing it usually leads to
-more insight.
-
-[0] <https://www.dhammatalks.org/books/#/books/TenPerfections/Section0001.html>
-[1] <https://www.fsf.org/news/publication-of-the-fsf-funded-white-papers-on-questions-around-copilot>

CONTRIBUTING

@@ -1,5 +1,3 @@
-Make sure to read our code of conduct in the CONDUCT file.
-
 When contributing a pull request to the main branch, please sign your commits
 with a PGP key and add your name and the year to the bottom of the list of
 copyright holders for the file. For example, an existing copyright header might

Makefile

@@ -1,88 +1,63 @@
 # Copyright (c) 2023–2024 Emma Tebibyte <emma@tebibyte.media>
 # Copyright (c) 2023–2024 DTB <trinity@trinity.moe>
 # Copyright (c) 2023 Sasha Koshka <sashakoshka@tebibyte.media>
-# Copyright (c) 2024 Aaditya Aryal <aryalaadi123@gmail.com>
 # SPDX-License-Identifier: FSFAP
 #
 # 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 any warranty.
 
-# The octal escape \043 is utilized twice in this file as make(1p) will
-# interpret a hash in a rule as an inline comment.
-
 .POSIX:
+.PRAGMA: posix_202x # future POSIX standard support à la pdpmake(1)
+.PRAGMA: command_comment # breaks without this?
 
-DESTDIR ?= dist
+PREFIX=/usr/local
-PREFIX ?= /usr/local
 
-MANDIR != [ $(PREFIX) = / ] && printf '/usr/share/man\n' \
+CC=cc
-	|| printf '/share/man\n'
+MAKE=make
-SYSEXITS != printf '\043include <sysexits.h>\n' | cpp -M - | sed 's/ /\n/g' \
+RUSTC=rustc
-	| sed -n 's/sysexits\.h//p' || printf 'include\n'
-
-CC ?= cc
-RUSTC ?= rustc
-RUSTLIBS = --extern getopt=build/o/libgetopt.rlib \
-	--extern sysexits=build/o/libsysexits.rlib \
-	--extern strerror=build/o/libstrerror.rlib
-CFLAGS += -I$(SYSEXITS)
 
 .PHONY: all
-all: docs dj false fop hru intcmp mm npc rpn scrut str strcmp swab true
+all: dj false fop hru intcmp rpn scrut str strcmp true
 
-# keep build/include until bindgen(1) has stdin support
-# https://github.com/rust-lang/rust-bindgen/issues/2703
 build:
-	mkdir -p build/bin build/docs build/include build/lib build/o build/test
+	# keep build/include until bindgen(1) has stdin support
+	# https://github.com/rust-lang/rust-bindgen/issues/2703
+	mkdir -p build/bin build/include build/lib build/o build/test
 
 .PHONY: clean
 clean:
-	rm -rf build dist
+	rm -rf build/ dist/
 
 dist: all
-	mkdir -p $(DESTDIR)/$(PREFIX)/bin $(DESTDIR)/$(PREFIX)/share/man/man1
+	mkdir -p dist/bin dist/share/man/man1
-	cp build/bin/* $(DESTDIR)/$(PREFIX)/bin
+	cp build/bin/* dist/bin/
-	cp build/docs/*.1 $(DESTDIR)/$(PREFIX)/$(MANDIR)/man1
+	cp docs/*.1 dist/share/man/man1/
 
 .PHONY: install
 install: dist
-	cp -r $(DESTDIR)/* /
+	mkdir -p $(PREFIX)
+	cp -r dist/* $(PREFIX)/
 
 .PHONY: test
-test: build /tmp/getopt
+test: build
-	/tmp/getopt
 	tests/posix-compat.sh
+	$(RUSTC) --test src/getopt-rs/lib.rs -o build/test/getopt
+	$(MAKE) -f Testfile
 
-/tmp/getopt: src/libgetopt.rs
+build/o/libsysexits.rlib: build
-	$(RUSTC) --test -o /tmp/getopt src/libgetopt.rs
+	# bandage solution until bindgen(1) gets stdin support
-
+	printf '#define EXIT_FAILURE 1\n' | cat - include/sysexits.h \
-.PHONY: docs
+		> build/include/sysexits.h 
-docs: docs/ build
-	for file in docs/*; do original="$$(sed -n '/^\.TH/p' <"$$file")"; \
-		title="$$(printf '%s\n' "$$original" | sed \
-		"s/X\.X\.X/$$(git describe --tags --long | cut -d'-' -f1)/g")"; \
-		sed "s/$$original/$$title/g" <"$$file" >"build/$$file"; done
-
-.PHONY: rustlibs
-rustlibs: build/o/libsysexits.rlib build/o/libgetopt.rlib \
-	build/o/libstrerror.rlib
-
-build/o/libgetopt.rlib: build src/libgetopt.rs
-	$(RUSTC) $(RUSTFLAGS) --crate-type=lib --crate-name=getopt \
-		-o $@ src/libgetopt.rs
-
-build/o/libstrerror.rlib: build src/libstrerror.rs
-	$(RUSTC) $(RUSTFLAGS) --crate-type=lib -o $@ \
-		src/libstrerror.rs
-
-build/o/libsysexits.rlib: build/include/sysexits.h
 	bindgen --default-macro-constant-type signed --use-core --formatter=none \
-		build/include/sysexits.h | $(RUSTC) $(RUSTFLAGS) --crate-type lib -o $@ -
+		"$$(printf '#include <sysexits.h>\n' \
+			| cpp -M -idirafter "build/include" - \
+			| sed 's/ /\n/g' | grep sysexits.h)" \
+		| $(RUSTC) $(RUSTFLAGS) --crate-type lib -o build/o/libsysexits.rlib -
 
-# bandage solution until bindgen(1) gets stdin support
+build/o/libgetopt.rlib: src/getopt-rs/lib.rs
-build/include/sysexits.h: build $(SYSEXITS)sysexits.h
+	$(RUSTC) $(RUSTFLAGS) --crate-type=lib --crate-name=getopt \
-	printf '\043define EXIT_FAILURE 1\n' | cat - $(SYSEXITS)sysexits.h > $@
+		-o build/o/libgetopt.rlib src/getopt-rs/lib.rs
 
 .PHONY: dj
 dj: build/bin/dj
@@ -96,33 +71,29 @@ build/bin/false: src/false.c build
 
 .PHONY: fop
 fop: build/bin/fop
-build/bin/fop: src/fop.rs build rustlibs
+build/bin/fop: src/fop.rs build build/o/libgetopt.rlib build/o/libsysexits.rlib
-	$(RUSTC) $(RUSTFLAGS) $(RUSTLIBS) -o $@ src/fop.rs
+	$(RUSTC) $(RUSTFLAGS) --extern getopt=build/o/libgetopt.rlib \
+		--extern sysexits=build/o/libsysexits.rlib \
+		-o $@ src/fop.rs
 
 .PHONY: hru
 hru: build/bin/hru
-build/bin/hru: src/hru.rs build rustlibs 
+build/bin/hru: src/hru.rs build build/o/libgetopt.rlib build/o/libsysexits.rlib
-	$(RUSTC) $(RUSTFLAGS) $(RUSTLIBS) -o $@ src/hru.rs
+	$(RUSTC) $(RUSTFLAGS) --extern getopt=build/o/libgetopt.rlib \
+		--extern sysexits=build/o/libsysexits.rlib \
+		-o $@ src/hru.rs
 
 .PHONY: intcmp
 intcmp: build/bin/intcmp
 build/bin/intcmp: src/intcmp.c build
 	$(CC) $(CFLAGS) -o $@ src/intcmp.c
 
-.PHONY: mm
-mm: build/bin/mm
-build/bin/mm: src/mm.c build
-	$(CC) $(CFLAGS) -o $@ src/mm.c
-
-.PHONY: npc
-npc: build/bin/npc
-build/bin/npc: src/npc.c build
-	$(CC) $(CFLAGAS) -o $@ src/npc.c
-
 .PHONY: rpn
 rpn: build/bin/rpn
-build/bin/rpn: src/rpn.rs build rustlibs
+build/bin/rpn: src/rpn.rs build build/o/libsysexits.rlib
-	$(RUSTC) $(RUSTFLAGS) $(RUSTLIBS) -o $@ src/rpn.rs
+	$(RUSTC) $(RUSTFLAGS) \
+		--extern sysexits=build/o/libsysexits.rlib \
+		-o $@ src/rpn.rs
 
 .PHONY: scrut
 scrut: build/bin/scrut
@@ -139,11 +110,6 @@ strcmp: build/bin/strcmp
 build/bin/strcmp: src/strcmp.c build
 	$(CC) $(CFLAGS) -o $@ src/strcmp.c
 
-.PHONY: swab
-swab: build/bin/swab
-build/bin/swab: src/swab.rs build rustlibs
-	$(RUSTC) $(RUSTFLAGS) $(RUSTLIBS) -o $@ src/swab.rs
-
 .PHONY: true
 true: build/bin/true
 build/bin/true: src/true.c build

README

@@ -1,29 +1,28 @@
 “Seek not to walk the path of the masters; seek what they sought.”
 – Matsuo Basho
 
-The Bonsai harakit utilities are a replacement for standard POSIX utilities
+The Bonsai core utilities are the result of the careful examination of the
-which aim to fill its niche while expanding on their capabilities. These new
+current state of POSIX and Unix utilies. The Unix Philosophy, “do one thing and
-tools are the result of the careful examination of the current state of POSIX
+do it well” is its core but these tools do not cling to the names of the past.
-and Unix utilies. The Unix Philosophy of “do one thing and do it well” are their
-core but they avoid clinging to the past.
 
 The era of the original Unix tools has been long and fruitful, but they have
-their flaws. This project originated from frustrations with the way certain
+their flaws. The new, non-POSIX era of this project started with frustration
-tools work and how other projects that extend POSIX don’t make anything better.
+with the way certain tools work and how other projects that extend POSIX don’t
+make anything better.
 
 This project will not follow in the footsteps of GNU; extensions of POSIX will
 not be found here. GNU extensions are a gateway to the misuse of the shell. The
-harakit utilities will intentionally discourage use of the shell for purposes
+Bonsai core utilities will intentionally discourage use of the shell for
-beyond its scope.
+purposes beyond its scope.
 
 See docs/ for more on the specific utilities currently implemented.
 
 Building
 
-Harakit utilities require a POSIX-compliant environment to compile, including a
+The coreutils require a POSIX-compliant environment to compile, including a C
-C compiler and preprocessor (cc(1) and cpp(1) by default), an edition 2023 Rust
+compiler and preprocessor (cc(1) and cpp(1) by default) with the -idirafter
-compiler (rustc(1) by default), bindgen(1), and a POSIX-compliant make(1)
+flag, a Rust compiler (rustc(1) by default), bindgen(1), and a POSIX-compliant
-utility.
+make(1) utility.
 
 To build and install:
 
@@ -39,7 +38,7 @@ To test the utilities:
 
 $ make test
 
-To remove all build and distributable files:
+To remove all untracked files:
 
 $ make clean
 

Testfile

@@ -0,0 +1,78 @@
+#!/usr/bin/env make
+# Copyright (c) 2024 DTB <trinity@trinity.moe>
+# SPDX-License-Identifier: FSFAP
+#
+# 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 any warranty.
+
+BIN = build/bin
+MAKE = make -B
+
+DEFENDANTS = dj false intcmp strcmp true
+.PHONY: all $(DEFENDANTS)
+all: $(DEFENDANTS)
+
+$(BIN)/dj:
+	$(MAKE) dj
+
+$(BIN)/false:
+	$(MAKE) false
+
+$(BIN)/intcmp:
+	$(MAKE) intcmp
+
+$(BIN)/strcmp:
+	$(MAKE) strcmp
+
+$(BIN)/true:
+	$(MAKE) true
+
+dj: $(BIN)/dj $(BIN)/strcmp
+	sh -c "! $(BIN)/dj -h"
+	# This test is theoretically Linux-dependent; write(2) should return -1 on
+	# error.
+	# Right now dj(1) interprets the return value of write(2) as the amount of
+	# bytes written. This can decrement the stored quantity of bytes written,
+	# which is an int, so doesn't underflow but goes negative. dj(1) tries to
+	# again to write(2) if an error occurs in which no bytes are written, so in
+	# total two write(2)s are attempted and so the written byte quantity is -2.
+	# This is a bug and will change, but for now is at least documented.
+	sh -ec "\
+		$(BIN)/dj -Hi /dev/zero -o /dev/full \
+		| xargs -I out $(BIN)/strcmp '1+0 > 0+0; 1024 > -2' out"
+	# Read nothing from /dev/null, write nothing to /dev/null.
+	sh -ec "\
+		$(BIN)/dj -Hi /dev/null -o /dev/null \
+		| xargs -I out $(BIN)/strcmp '0+0 > 0+0; 0 > 0' out"
+
+false: $(BIN)/false
+	sh -c "! $(BIN)/false"
+	sh -c "! $(BIN)/false -h"
+
+intcmp: $(BIN)/intcmp
+	$(BIN)/intcmp -e   3 3 3
+	$(BIN)/intcmp -g   3 2 1
+	$(BIN)/intcmp -l   1 2 3
+	$(BIN)/intcmp -ge  3 3 1
+	$(BIN)/intcmp -le  1 3 3
+	$(BIN)/intcmp -gl  1 2 3
+	$(BIN)/intcmp -egl 3 1 1 2
+	sh -c "! $(BIN)/intcmp -e   1 2 3"
+	sh -c "! $(BIN)/intcmp -g   1 3 3"
+	sh -c "! $(BIN)/intcmp -l   3 3 1"
+	sh -c "! $(BIN)/intcmp -ge  1 2 3"
+	sh -c "! $(BIN)/intcmp -le  3 2 1"
+	sh -c "! $(BIN)/intcmp -gl  3 3 3"
+	sh -c "! $(BIN)/intcmp -egl foo"
+
+strcmp: $(BIN)/strcmp
+	$(BIN)/strcmp equals equals
+	sh -c "! $(BIN)/strcmp inequals equals"
+	$(BIN)/strcmp - -
+	sh -c "! $(BIN)/strcmp -h"
+	sh -c "! $(BIN)/strcmp nocmp"
+
+true:
+	$(BIN)/true
+	$(BIN)/true -h

docs/dj.1

@@ -1,181 +1,160 @@
 .\" Copyright (c) 2024 DTB <trinity@trinity.moe>
-.\" Copyright (c) 2024 Emma Tebibyte <emma@tebibyte.media>
 .\"
 .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
 .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
-.\"
+
-.TH DJ 1 2024-06-17 "Harakit X.X.X"
+.TH dj 1
+
 .SH NAME
+
 dj \(en disk jockey
-.\"
+
 .SH SYNOPSIS
 
 dj
-.RB [ -AdHnq ]
+.RB ( -AdHnq )
-.RB [ -a\ byte ]
+.RB ( -a
-.RB [ -c\ count ]
+.RB [ byte ])
+.RB ( -c
+.RB [ count ])
 
-.RB [ -i\ file ]
+.RB ( -i
-.RB [ -b\ block_size ]
+.R [
-.RB [ -s\ offset ]
+.B input file
+.R ])
+.RB ( -b
+.R [
+.B input block size
+.R ])
+.RB ( -s
+.R [
+.B input offset
+.R ])
 
-.RB [ -o\ file ]
+.RB ( -o
-.RB [ -B\ block_size ]
+.R [
-.RB [ -S\ offset ]
+.B output file
-.\"
+.R ])
-.SH DESCRIPTION
+.RB ( -B
+.R [
+.B output block size
+.R ])
+.RB ( -S
+.R [
+.B output offset
+.R ])
 
-Perform precise read and write operations on files. This utility is useful for
+.SH USAGE
-reading and writing binary data to and from disks.
 
-This manual page uses the terms \(lqskip\(rq and \(lqseek\(rq to refer to moving
+The
-to a specified byte by index in the input and output of the program
+.B -i
-respectively. This language is inherited from the
+option takes a path as an argument to open and use in place of standard input.
-.BR dd (1p)
+The
-utility and used here to decrease ambiguity.
+.B -o
-
+option does the same in place of standard output. Dj does not truncate output
-When seeking or skipping to a byte, writing or reading starts at the byte
+files and instead writes over the bytes in the existing file.
-immediately subsequent to the specified byte.
+.PP
-.\"
+The
-.SH OPTIONS
-
-.IP \fB-i\fP\ \fIfile\fP
-Takes a file path as an argument and opens it for use as an input.
-.IP \fB-b\fP\ \fIblock_size\fP
-Takes a numeric argument as the size in bytes of the input buffer, the default
-being 1024.
-.IP \fB-s\fP\ \fIoffset\fP
-Takes a numeric argument as the number of bytes to skip into the input
-before starting to read. If the standard input is used, bytes read to this point
-are discarded.
-.IP \fB-o\fP\ \fIfile\fP
-Takes a file path as an argument and opens it for use as an output.
-.IP \fB-B\fP\ \fIblock_size\fP
-Does the same as
 .B -b
-but for the output buffer.
+option takes a numeric argument as the size in bytes of the input buffer and
-.IP \fB-S\fP\ \fIoffset\fP
+the
-Seeks a number of bytes through the output before starting to write from
+.B -B
-the input. If the output is a stream, null characters are printed.
+option does the same for the output buffer, the default for both being 1024
-.IP \fB-a\fP\ \fIbyte\fP
+bytes, or one kibibyte (KiB).
-Accepts a single literal byte with which the input buffer is padded in the event
+.PP
-of an incomplete read from the input file.
+The
-.IP \fB-A\fP
+.B -s
-Specifying this option pads the input buffer with null bytes in the event of an
+option takes a numeric argument as the number of bytes to skip into the input
-incomplete read. This is equivalent to specifying
+before starting to read, and the
+.B -S
+option skips a number of bytes through the output before starting to write from
+the input. If the input is a stream the bytes are read and discarded. If the
+output is a stream, nul characters are printed.
+.PP
+The
 .B -a
-with a null byte instead of a character.
+option takes one argument of one byte in length and pads the input buffer with
-.IP \fB-c\fP\ \fIcount\fP
+that byte in the event that a read doesn't fill the input buffer, and the
-Specifies a number of reads to make. The default is 0, in which case the
+.B -A
-input is read until a partial or empty read is made.
+option takes no arguments and pads with nuls.
-.IP \fB-d\fP
+The
-Prints invocation information before program execution as described in the
+.B -c
-DIAGNOSTICS section. Each invocation increments the debug level of the
+option specifies an amount of reads to make, and if 0 (the default) dj will
-program.
+continue reading until a partial or empty read.
-.IP \fB-H\fP
+.PP
-Prints diagnostics messages in a human-readable manner as described in the
+On a partial or empty read, dj prints a diagnostic message (unless the
-DIAGNOSTICS section.
+.B -q
-.IP \fB-n\fP
+option is specified) and exits (unless the
-Retries failed reads once before exiting.
+.B -n
-.IP \fB-q\fP
+option is specified, in which case only two consecutive empty reads will cause
-Suppresses error messages which print when a read or write is partial or
+dj to exit).
-empty. Each invocation decrements the debug level of the program.
+At exit, usage statistics are printed unless the option
-.\"
+.B -q
-.SH STANDARD INPUT
+is specified a second time. The
+.B -H
+option will make these diagnostics human-readable.
 
-The standard input shall be used as an input if no inputs are specified or if
-one or more of the input files is \(lq-\(rq.
-.\"
-.SH STANDARD OUTPUT
-The standard output shall be used as an output if no inputs are specified or if
-one or more of the input files is \(lq-\(rq.
-.\"
 .SH DIAGNOSTICS
 
-On a partial or empty read, unless the
+The
-.B -q
+.B -d
-option is specified, a diagnostic message is printed. Then, the program exits
+option prints all information, user-specified or otherwise, before program
-unless the
+execution.
-.B -n
+.PP
-option is specified.
+When dj exits, by default statistics are printed for input and output to
-
+standard error in the following format:
-By default, statistics are printed for input and output to the standard error in
+.PP
-the following format:
+.R {records read} {ASCII unit separator} {partial records read}
-
+.R {ASCII record separator} {records written} {ASCII unit separator}
-.RS
+.R {partial records written} {ASCII group separator} {bytes read}
-{records read} {ASCII unit separator} {partial records read}
+.R {ASCII record separator} {bytes written} {ASCII file separator}
-{ASCII record separator} {records written} {ASCII unit separator}
+.PP
-{partial records written} {ASCII group separator} {bytes read}
-{ASCII record separator} {bytes written} {ASCII file separator}
-.RE
-
-This format for diagnostic output is designed to be machine-parseable for
-convenience. For a more human-readable format, the
-.B -H
-option may be specified. In this event, the following format is used instead:
-
-.RS
-{records read} '+' {partial records read} '>' {records written}
-'+' {partial records written} ';' {bytes read} '>' {bytes written}
-{ASCII line feed}
-.RE
-
 If the
-.B -d
+.B -H
-option is specified, debug information will be printed at the beginning of
+option is specified dj instead uses this following format:
-execution. This output contains information regarding how the program was
+.PP
-invoked. The following example is the result of running the program with
+.R {records read} '+' {partial records read} '>' {records written}
-.B -d
+.R '+' {partial records written} ';' {bytes read} '>' {bytes written}
-as the only argument:
+.R {ASCII line feed}
-
+.PP
-.RS
+The
-argv0=dj
+.B -q
-in=<stdin>      ibs=1024        skip=0  align=ff       count=0
+option suppresses error messages which print when a read or write is partial or
-out=<stdout>    obs=1024        seek=0  debug= 3       noerror=0
+empty and when used twice suppresses diagnostic output entirely.
-.RE
+.PP
-
+In non-recoverable errors that don't pertain to dj's read-write cycle, a
-In non-recoverable errors that don\(cqt pertain to the read-write cycle, a
+diagnostic message is printed and dj exits with the appropriate sysexits(3)
-diagnostic message is printed and the program exits with the appropriate
-.BR sysexits.h (3)
 status.
-.\"
+
 .SH BUGS
 
 If
 .B -n
-is specified along with the
+is specified along with a specified count, actual byte output may be lower than
-.B -c
+expected (the product of the count multiplied by the input block size). If the
-option and a count, actual byte output is the product of the count and the input
-block size and therefore may be lower than expected. If the
 .B -a
 or
 .B -A
-options are specified, this could make written data nonsensical.
+options are used this could make data written nonsensical.
-.\"
+.PP
-.SH CAVEATS
-
-Existing files are not truncated on ouput and are instead overwritten.
-
 Many lowercase options have capitalized variants and vice-versa which can be
 confusing. Capitalized options tend to affect output or are more intense
 versions of lowercase options.
-.\"
+
 .SH RATIONALE
 
-This program was based on the
+Dj was modeled after the dd utility specified in POSIX but adds additional
-.BR dd (1p)
+features: typical option formatting, allowing seeks to be specified in bytes
-utility as specified in POSIX. While character conversion may have been the
+rather than in blocks, allowing arbitrary bytes as padding, and printing in a
-original intent of
+format that's easy to parse for machines. It also neglects character
-.BR dd (1p),
+conversion, which may be dd's original intent but is irrelevant to its modern
-it is irrelevant to its modern use. Because of this, this program eschews
+use.
-character conversion and adds typical option formatting, allowing seeks to be
+
-specified in bytes rather than in blocks, allowing arbitrary bytes as padding,
-and printing in a format that\(cqs easy for machines to parse.
-.\"
 .SH COPYRIGHT
 
-Copyright \(co 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
+Copyright (C) 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
 <https://gnu.org/licenses/agpl.html>.
-.\"
+
 .SH SEE ALSO
-.BR dd (1p)
+
+dd(1)

docs/false.1

@@ -1,35 +1,35 @@
 .\" Copyright (c) 2022, 2024 DTB <trinity@trinity.moe>
-.\" Copyright (c) 2023–2024 Emma Tebibyte <emma@tebibyte.media>
+.\" Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media>
 .\"
 .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
 .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
-.\"
+
-.TH FALSE 1 2024-06-06 "Harakit X.X.X"
+.TH FALSE 1
+
 .SH NAME
+
 false \(en do nothing, unsuccessfully
-.\"
+
 .SH DESCRIPTION
 
-Do nothing regardless of operands or standard input. An exit code of 1 will
+False does nothing regardless of operands or standard input.
-always be returned.
+False will always return an exit code of 1.
-.\"
+
 .SH RATIONALE
 
-In POSIX.1-2017,
+False exists for the construction of control flow and loops based on a failure.
-.BR false (1p)
+
-exists for the construction of control flow and loops based on a failure. This
+False functions as described in POSIX.1-2017.
-implementation functions as described in that standard.
+
-.\"
 .SH AUTHOR
 
-Written by Emma Tebibyte
+Written by Emma Tebibyte <emma@tebibyte.media>.
-.MT emma@tebibyte.media
+
-.ME .
-.\"
 .SH COPYRIGHT
 
 This work is marked with CC0 1.0. To see a copy of this license, visit
 <http://creativecommons.org/publicdomain/zero/1.0>.
-.\"
+
 .SH SEE ALSO
-.BR true (1p)
+
+true(1p)

docs/fop.1

@@ -1,62 +0,0 @@
-.\" Copyright (c) 2024 DTB <trinity@trinity.moe>
-.\" Copyright (c) 2024 Emma Tebibyte <emma@tebibyte.media>
-.\"
-.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
-.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
-.\"
-.TH FOP 1 2024-06-17 "Harakit X.X.X"
-.SH NAME
-fop \(en field operator
-.\"
-.SH SYNOPSIS
-
-fop
-.RB ( -d )
-.RB [ delimiter ]
-.RB index 
-.RB program...
-.\"
-.SH DESCRIPTION
-
-Performs operations on specified fields in data read from the standard input.
-.\"
-.SH OPTIONS
-
-.IP \fB-d\fP\ \fIdelimiter\fP
-Sets a delimiter by which the input data will be split into fields. The default
-is an ASCII record separator.
-.\"
-.SH CAVEATS
-
-Field indices are zero-indexed, which may be unexpected behavior for some users.
-.\"
-.SH RATIONALE
-
-With the assumption that tools will output data separated with ASCII field
-separators, there is a need for the ability to modify select fields in this data
-easily and quickly.
-
-The idea for this utility originated in the fact that the GNU
-.BR ls (1)
-utility contains a
-.B -h
-option which enables human-readable units in file size outputs. This
-functionality was broken out into
-.BR hru (1),
-but there was no easy way to modify the field in the ouput of
-.BR ls (1p)
-without creating a new tool.
-.\"
-.SH AUTHOR
-
-Written by Emma Tebibyte
-.MT emma@tebibyte.media
-.ME .
-.\"
-.SH COPYRIGHT
-
-Copyright \(co 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later
-<https://gnu.org/licenses/agpl.html>.
-.\"
-.SH SEE ALSO
-.BR sed (1p)

docs/hru.1

@@ -2,68 +2,56 @@
 .\"
 .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
 .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
-.\"
+
-.TH HRU 1 2024-06-17 "Harakit X.X.X"
+.TH rpn 1
+
 .SH NAME
+
 hru \(en human readable units
-.\"
+
 .SH SYNOPSIS
 
 hru
-.\"
+
 .SH DESCRIPTION
 
-Convert counts to higher units.
+Hru reads byte counts in the form of whole numbers from the standard input and
-
+writes to the standard output the same number converted one of the units of data
-Byte counts will be read in the form of whole numbers from the standard input
+defined by the International System of Units.
-and be written to the standard output the same number converted to a higher unit
-of data as defined by the \fIInternational System of Units\fP.
 
 The program will convert the byte count to the highest unit possible where the
 value is greater than one.
-.\"
+
 .SH DIAGNOSTICS
 
-If encountering non-integer characters in the standard input, the program will
+If encountering non-integer characters in the standard input, hru will exit with
-exit with the appropriate error code as defined by
+the appropriate error code as defined by sysexits.h(3) and print an error
-.BR sysexits.h (3)
+message.
-and print an error message.
+
-.\"
 .SH RATIONALE
 
-The GNU project\(cqs
+The GNU project’s ls(1) implementation contains a human-readable option (-h)
-.BR ls (1)
+that, when specified, makes the tool print size information in a format more
-implementation contains a human-readable option (\fB-h\fP) that, when specified,
+immediately readable. This functionality is useful not only in the context of
-makes the tool print size information in a format more immediately
+ls(1) so the decision was made to split it into a new tool. The original
-readable. This functionality is useful not only in this context, so the decision
+functionality in GNU’s ls(1) can be emulated with fop(1) combined with this
-was made to split it into a new tool. The original functionality from GNU\(cqs
+program.
-.BR ls (1)
+
-can be emulated with
-.BR fop (1)
-combined with this program.
-.\"
 .SH STANDARDS
 
-The standard unit prefixes as specified by the
+Hru follows the standard unit prefixes as specified by the Bureau International
-.I Bureau International des Poids et Mesures
+des Poids et Mesures (BIPM) in the ninth edition of The International System of
-.RI ( BIPM )
+Units (SI).
-in the ninth edition of
+
-.I The International System of Units
-.RI ( SI )
-are utilized for the ouput of conversions.
-.\"
 .SH AUTHOR
 
-Written by Emma Tebibyte
+Written by Emma Tebibyte <emma@tebibyte.media>.
-.MT emma@tebibyte.media
+
-.ME .
-.\"
 .SH COPYRIGHT
 
-Copyright \(co 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later
+Copyright (c) 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later
 <https://gnu.org/licenses/agpl.html>.
-.\"
+
 .SH SEE ALSO
-GNU
+
-.BR ls (1),
+GNU ls(1), The International System of Units (SI) 9th Edition
-.I The International System of Units (SI) 9th Edition

docs/intcmp.1

@@ -1,103 +1,78 @@
 .\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe>
-.\" Copyright (c) 2023–2024 Emma Tebibyte <emma@tebibyte.media>
+.\" Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media>
 .\"
 .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
 .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
-.\"
+
-.TH INTCMP 1 2024-06-06 "Harakit X.X.X"
+.TH intcmp 1
+
 .SH NAME
+
 intcmp \(en compare integers
-.\"
+
 .SH SYNOPSIS
 
 intcmp
-.RB [ -egl ]\ integer\ integer...
+.RB ( -eghl )
+.RB [ integer ]
+.RB [ integer... ]
+
 .SH DESCRIPTION
-Compare integers to each other.
-.\"
-.SH OPTIONS
 
-.IP \fB-e\fP
+Intcmp compares integers.
-Permits given integers to be equal to each other.
+
-.IP \fB-g\fP
+.SH USAGE
-Permits a given integer to be greater than the following integer.
+
-.IP \fB-l\fP
+The -e option permits given integers to be equal to each other. If combined
-Permits a given integer to be less than the following integer.
+with -g or -l, only adjacent integers in the argument sequence can be equal.
-.\"
+.PP
-.SH EXAMPLES
+The -g option permits a given integer to be greater than the following integer.
+.PP
+The -l option permits a given integer to be less than the following integer.
+.PP
+It may help to think of the -e, -g, and -l options as equivalent to the
+infix algebraic “=”, “>”, and “<” operators respectively, with each option
+putting its symbol between every given integer. For example,
+.R intcmp -l 1 2 3
+is equivalent to evaluating "1 < 2 < 3".
 
-It may help to think of the
-.BR -e ,
-.BR -g ,
-and
-.B -l
-options as equivalent to the infix algebraic \(lq=\(rq, \(lq>\(rq, and \(lq<\(rq
-operators respectively, with each option putting its symbol between every given
-integer. The following example is equivalent to evaluating \(lq1 < 2 < 3\(rq:
-\"
-.RS
-intcmp -l 1 2 3
-.RE
-.\"
 .SH DIAGNOSTICS
 
-The program will exit with a successfully for a valid expression and with an
+Intcmp exits 0 for a valid expression and 1 for an invalid expression.
-error code of 1 for an invalid expression.
+.PP
+Intcmp prints a debug message and exits with the appropriate sysexits(3) error
+code in the event of an error.
 
-In the event of an error, a debug message will be printed and the program will
-exit with the appropriate
-.BR sysexits.h (3)
-error code.
-.\"
 .SH BUGS
 
-.BR -egl ,
+There are multiple ways to express compound comparisons; “less than or equal
-\(lqequal to or less than or greater than\(rq, always exits successfully for
+to” can be -le or -el, for example.
-valid program usage and may be abused to function as an integer validator. Use
+.PP
-.BR str (1)
+The inequality comparison is -gl or -lg for “less than or greater than”; this
-instead.
+is elegant but unintuitive.
-.\"
+.PP
-.SH CAVEATS
+-egl, "equal to or less than or greater than", exits 0 no matter what for valid
+program usage and may be abused to function as an integer validator.
+Use str(1) instead.
 
-There are multiple ways to express compound comparisons; \(lqless than or equal
-to\(rq can be
-.B -le
-or
-.BR -el ,
-for example.
-
-The inequality comparison is
-.B -gl
-.B or
-.B -lg
-for \(lqless than or greater than\(rq;
-this is elegant but unintuitive.
-.\"
 .SH RATIONALE
 
 The traditional tool for integer comparisons in POSIX and other Unix shells has
-been
+been test(1). This tool also handles string comparisons and file scrutiny.
-.BR test (1).
+These parts of its functionality have been broken out into multiple utilities.
-This tool also handles string comparisons and file scrutiny. These parts of its
+
-functionality have been broken out into multiple utilities.
+Strcmp’s functionality may be performed on a POSIX-compliant system with
+test(1p).
 
-This program\(cqs functionality may be performed on a POSIX-compliant system
-with
-.BR test (1p).
-.\"
 .SH AUTHOR
 
-Written by DTB
+Written by DTB <trinity@trinity.moe>.
-.MT trinity@trinity.moe
+
-.ME .
-.\"
 .SH COPYRIGHT
-.\"
+
-Copyright \(co 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
+Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
 <https://gnu.org/licenses/gpl.html>.
-.\"
+
 .SH SEE ALSO
-.BR scrut (1),
+
-.BR strcmp (1),
+strcmp(1), scrut(1), str(1), test(1p)
-.BR str (1),
-.BR test (1p)

docs/mm.1

@@ -1,71 +0,0 @@
-.\" Copyright (c) 2024 DTB <trinity@trinity.moe>
-.\"
-.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
-.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
-.\"
-.TH MM 1 2024-06-17 "Harakit X.X.X"
-.SH NAME
-mm \(en middleman
-.\"
-.SH SYNOPSIS
-
-mm
-.RB [ -aenu ]
-.RB [ -i\ input ]
-.RB [ -o\ output ]
-.\"
-.SH DESCRIPTION
-
-Catenate input files and write them to the start of each output file or stream.
-.\"
-.SH OPTIONS
-
-.IP \fB-a\fP
-Opens subsequent outputs for appending rather than updating.
-.IP \fB-e\fP
-Use the standard error as an output.
-.IP \fB-i\fP\ \fIinput\fP
-Opens a path as an input. If one or more of the input files is \(lq-\(rq or if
-no inputs are specified, the standard input shall be used.
-.IP \fB-o\fP\ \fIoutput\fP
-Opens a path as an output. If one or more of the output files is \(lq-\(rq or if
-no outputs are specified, the standard output shall be used.
-.IP \fB-u\fP
-Ensures neither input or output will be buffered.
-.IP \fB-n\fP
-Causes SIGINT signals to be ignored.
-.\"
-.SH DIAGNOSTICS
-
-If an output cannot be written to, an error occurs; however, exiting will be 
-deferred until writing to any other specified outputs completes.
-
-When an error is encountered, a diagnostic message is printed and the program
-exits with the appropriate
-.BR sysexits.h (3)
-status.
-.\"
-.SH CAVEATS
-
-Existing files are not truncated on ouput and are instead overwritten.
-.\"
-.SH RATIONALE
-
-The
-.BR cat (1p)
-and
-.BR tee (1p)
-programs specified in POSIX together provide similar functionality. The
-separation of the two sets of functionality into separate APIs seemed
-unncessary.
-.\"
-.SH COPYRIGHT
-
-Copyright \(co 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
-<https://gnu.org/licenses/agpl.html>.
-.\"
-.SH SEE ALSO
-.BR cat (1p),
-.BR dd (1),
-.BR dj (1),
-.BR tee (1p)

docs/npc.1

@@ -1,74 +1,68 @@
 .\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe>
-.\" Copyright (c) 2023–2024 Emma Tebibyte <emma@tebibyte.media>
+.\" Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media>
 .\"
 .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
 .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
-.\"
+
-.TH NPC 1 2024-06-17 "Harakit X.X.X"
+.TH npc 1
+
 .SH NAME
+
 npc \(en show non-printing characters
-.\"
+
 .SH SYNOPSIS
 
 npc
-.RB [ -et ]
+.RB ( -eht )
-.\"
+
 .SH DESCRIPTION
 
-Print normally non-printing characters.
+Npc reads from standard input and writes to standard output, replacing non-
-
+printing characters with printable equivalents. Control characters print as a
-The program reads from standard input and writes to standard output, replacing
+carat ('^') followed by the character '@' through '_' corresponding to the
-non-printing characters with printable equivalents. Control characters print as
+character replaced (e.g. control-X becomes "^X"). The delete character (0x7F)
-a carat ('^') followed by the character '@' through '_' corresponding to the
+becomes "^?". Characters with the high bit set (>127) are printed as "M-"
-character replaced (e.g. control-X becomes '^X'). The delete character (0x7F)
-becomes '^?'. Characters with the high bit set (>127) are printed as 'M-'
 followed by the graphical representation for the same character without the
 high bit set.
-.\"
+.PP
-.SH OPTIONS
+The
+.B -e
+option prints a currency sign ('$') before each line ending.
+.PP
+The
+.B -t
+option prints tab characters as "^I" rather than a literal horizontal tab.
 
-.IP \fB-e\fP
-Prints a dollar sign ('$') before each newline.
-.IP \fB-t\fP
-Prints tab characters as '^I' rather than a literal horizontal tab.
-.\"
 .SH DIAGNOSTICS
 
-In the event of an error, a debug message will be printed and the program will
+Npc prints a debug message and exits with the appropriate sysexits(3) error
-exit with the appropriate
+code in the event of an error, otherwise it exits successfully.
-.BR sysexits.h (3)
+
-error code.
-.\"
 .SH BUGS
 
-The program operates in single-byte chunks regardless of intended encoding.
+Npc operates in single-byte chunks regardless of intended encoding.
-.\"
+
 .SH RATIONALE
 
 POSIX currently lacks a way to display non-printing characters in the terminal
-using a standard tool. A popular extension to
+using a standard tool. A popular extension to cat(1p), the -v option, is the
-.BR cat (1p),
+bandage solution GNU and other software suites use.
-the
+
-.B -v
+This functionality should be a separate tool because its usefulness extends
-option, is the bandage solution GNU and other software suites use.
+beyond that of cat(1p).
 
-This functionality is included in a separate tool because its usefulness extends
-beyond that of
-.BR cat (1p).
-.\"
 .SH AUTHOR
 
-Written by DTB
+Written by DTB <trinity@trinity.moe>.
-.MT trinity@trinity.moe
+
-.ME .
-.\"
 .SH COPYRIGHT
 
 Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
 <https://gnu.org/licenses/agpl.html>.
-.\"
+
 .SH SEE ALSO
-.BR cat (1p),
+
-.BR cat-v (1),
+cat(1p), cat-v(1)
+
 .I UNIX Style, or cat -v Considered Harmful
 by Rob Pike

docs/rpn.1

@@ -3,84 +3,68 @@
 .\"
 .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
 .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
-.\"
+
-.TH RPN 1 2024-06-17 "Harakit X.X.X"
+.TH rpn 1
+
 .SH NAME
+
 rpn \(en reverse polish notation evaluation
-.\"
+
 .SH SYNOPSIS
 
 rpn
-.RB [ numbers... ]
+.RB [numbers...]\ [operators...]
-.RB [ operators... ]
+
-.\"
 .SH DESCRIPTION
 
-Evaluate reverse polish notation.
+Rpn evaluates reverse polish notation expressions either read from the standard
+input or parsed from provided arguments. See the STANDARD INPUT section.
 
-The program evaluates reverse polish notation expressions read either from the
+Upon evaluation, rpn will print the resulting number on the stack to the
-standard input or parsed from provided arguments. See the STANDARD INPUT
+standard output. Any further specified numbers will be placed at the end of the
-section.
-
-Upon evaluation, the resulting number on the stack will be printed to the
-standard output. Any further numbers specified will be placed at the end of the
 stack.
 
-For information on for reverse polish notation syntax, see
+For information on for reverse polish notation syntax, see rpn(7).
-.BR rpn (7).
+
-.\"
 .SH STANDARD INPUT
 
-If arguments are specified, they are interpreted as an expression to be
+If arguments are passed to rpn, it interprets them as an expression to be
-evaluated. Otherwise, whitespace-delimited numbers and operations are read from
+evaluated. Otherwise, it reads whitespace-delimited numbers and operations from
 the standard input.
-.\"
+
 .SH DIAGNOSTICS
 
-In the event of an error, a debug message will be printed and the program will
+If encountering a syntax error, rpn will exit with the appropriate error code
-exit with the appropriate
+as defined by sysexits.h(3) and print an error message.
-.BR sysexits.h (3)
+
-error code; however, in the event of a syntax error, the program will print an
-error message and continue accepting input.
-.\"
 .SH CAVEATS
 
 Due to precision constraints and the way floats are represented in accordance
-with the
+with the IEEE Standard for Floating Point Arithmetic (IEEE 754), floating-point
-.I IEEE Standard for Floating Point Arithmetic
+arithmetic has rounding errors. This is somewhat curbed by using the
-(\fIIEEE 754\fP), floating-point arithmetic has rounding errors. This is
+machine epsilon as provided by the Rust standard library to which to round
-somewhat curbed by using the machine epsilon as provided by the Rust standard
+numbers. Because of this, variation is expected in the number of decimal places 
-library to which numbers are rounded. Because of this, variation is expected in
+rpn can handle based on the platform and hardware of any given machine.
-the number of decimal places the program can handle based on the platform and
+
-hardware of any given machine.
-.\"
 .SH RATIONALE
 
-An infix notation calculation utility,
+An infix notation calculation utility, bc(1p), is included in the POSIX
-.BR bc (1p),
+standard, but does not accept expressions as arguments; in scripts, any
-is included in the POSIX standard, but does not accept expressions as arguments;
+predefined, non-interactive input must be piped into the program. A dc(1)
-in scripts, any predefined, non-interactive input must be piped into the
+pre-dates the standardized bc(1p), the latter originally being a preprocessor
-program. A
+for the former, and was included in UNIX v2 onward. While it implements reverse
-.BR dc (1)
+polish notation, it still suffers from being unable to accept an expression as
-pre-dates the standardized
+an argument.
-.BR bc (1p),
+
-the latter originally being a preprocessor for the former, and was included in
-Second Edition UNIX and onward. While it implements reverse polish notation, it
-still suffers from being unable to accept an expression as an argument.
-.\"
 .SH AUTHOR
 
-Written by Emma Tebibyte
+Written by Emma Tebibyte <emma@tebibyte.media>.
-.MT emma@tebibyte.media
+
-.ME .
-.\"
 .SH COPYRIGHT
 
 Copyright (c) 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later
 <https://gnu.org/licenses/agpl.html>.
-.\"
+
 .SH SEE ALSO
-.BR bc (1p),
+
-.BR dc (1),
+bc(1p), dc(1), rpn(7), IEEE 754
-.BR rpn (7),
-.I IEEE 754

docs/scrut.1

@@ -1,86 +1,93 @@
 .\" Copyright (c) 2024 DTB <trinity@trinity.moe>
-.\" Copyright (c) 2024 Emma Tebibyte <emma@tebibyte.media>
 .\"
 .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
 .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
-.\"
+
-.TH SCRUT 1 2024-06-06 "Harakit X.X.X"
+.TH scrut 1
+
 .SH NAME
+
 scrut \(en scrutinize file properties
+
 .SH SYNOPSIS
 
 scrut
-.RB [ -LSbcdefgkprsuwx ]
+.RB ( -bcdefgkprsuwxLS )
-.B file...
+.RB [ file... ]
-.\"
+
 .SH DESCRIPTION
 
-Determine if files comply with requirements. If the given files comply with the
+Scrut determines if given files comply with the opted requirements.
-specified requirements, the program will exit successfully. Otherwise, it exits
+
-unsuccessfully.
-.\"
 .SH OPTIONS
 
-.IP \fB-L\fB
+.B -b
-Requires the given files to exist and be symbolic links.
+requires the given files to exist and be block special files.
-.IP \fB-S\fP
+.PP
-Requires the given files to exist and be sockets.
+.B -c
-.IP \fB-b\fP
+requires the given files to exist and be character special files.
-Requires the given files to exist and be block special files.
+.PP
-.IP \fB-c\fP
+.B -d
-Requires the given files to exist and be character special files.
+requires the given files to exist and be directories.
-.IP \fB-d\fP
+.PP
-Requires the given files to exist and be directories.
+.B -e
-.IP \fB-e\fP
+requires the given files to exist, and is redundant to any other option.
-Requires the given files to exist, and is redundant to any other option.
+.PP
-.IP \fB-f\fP
+.B -e
-Requires the given files to exist and be regular files.
+requires the given files to exist and be regular files.
-.IP \fB-g\fP
+.PP
-Requires the given files to exist and have their set group ID flags set.
+.B -g
-.IP \fB-k\fP
+requires the given files to exist and have their set group ID flags set.
-Requires the given files to exist and have their sticky bit set.
+.PP
-.IP \fB-p\fP
+.B -k
-Requires the given files to exist and be named pipes.
+requires the given files to exist and have their sticky bit set.
-.IP \fB-r\fP
+.PP
-Requires the given files to exist and be readable.
+.B -p
-.IP \fB-u\fP
+requires the given files to exist and be named pipes.
-Requires the given files to exist and have their set user ID flags set.
+.PP
-.IP \fB-w\fP
+.B -r
-Requires the given files to exist and be writable.
+requires the given files to exist and be readable.
-.IP \fB-x\fP
+.PP
-Requires the given files to exist and be executable.
+.B -u
-.\"
+requires the given files to exist and have their set user ID flags set.
-.SH DIAGNOSTICS
+.PP
+.B -w
+requires the given files to exist and be writable.
+.PP
+.B -x
+requires the given files to exist and be executable.
+.PP
+.B -L
+requires the given files to exist and be symbolic links.
+.PP
+.B -S
+requires the given files to exist and be sockets.
 
-When invoked incorrectly, a debug message will be printed and the program will
+.SH EXIT STATUS
-exit with the appropriate
-.BR sysexits.h (3)
-error code.
-.\"
-.SH RATIONALE 
 
-The 
+Scrut prints a debug message and exits unsuccessfully with the appropriate
-.BR test (1p)
+sysexits.h(3) error code if invoked incorrectly. Scrut exits successfully if
-utility contains functionality that was broken out into separate programs. Thus,
+the given files comply with their requirements and unsuccessfully otherwise.
-the scope of this program is narrower than it. Notably, the
+
+.SH STANDARDS
+
+Scrut is nearly compatible with POSIX's test utility though it is narrower in
+scope. Notably, the
 .B -h
 option is now invalid and therefore shows usage information instead of being an
 alias to the modern
 .B -L
 option.
-.\"
+
 .SH AUTHOR
 
-Written by DTB
+Written by DTB <trinity@trinity.moe>.
-.MT trinity@trinity.moe
+
-.ME .
-.\"
 .SH COPYRIGHT
 
-Copyright \(co 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
+Copyright © 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
 <https://gnu.org/licenses/agpl.html>.
-.\"
+
 .SH SEE ALSO
-.BR access (3p),
+
-.BR lstat (3p),
+access(3p), lstat(3p), test(1p)
-.BR test (1p)

docs/str.1

@@ -1,59 +1,58 @@
 .\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe>
-.\" Copyright (c) 2023–2024 Emma Tebibyte <emma@tebibyte.media>
+.\" Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media>
 .\"
 .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
 .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
-.\"
+
-.TH STR 1 2024-06-17 "Harakit X.X.X"
+.TH STR 1
+
 .SH NAME
-str \(en test string arguments
+
-.\"
+str \(en test the character types of string arguments
+
 .SH SYNOPSIS
 
 str
-.B type string...
+.RB [ type ]
-.\"
+.RB [ string... ]
+
 .SH DESCRIPTION
 
-Test the character types of string arguments.
+Str tests each character in an arbitrary quantity of string arguments against
+the function of the same name within ctype(3).
 
-The tests in this program are equivalent to the functions with the same names in
-.BR ctype.h (0p)
-and are the methods by which string arguments are tested.
-.\"
 .SH DIAGNOSTICS
 
-If all tests pass, the program will exit successfully. If any of the tests fail,
+Str exits successfully if all tests pass and unsuccessfully if a test failed.
-the program will exit unsuccessfully with an error code of 1.
+.PP
+Str will exit unsuccessfully if a string is empty, as none of its contents
+passed the test.
+.PP
+Str will print a message to standard error and exit unsuccessfully if used
+improperly.
 
-When invoked incorrectly, a debug message will be printed and the program will
+.SH DEPRECATED FEATURES
-exit with the appropriate
-.BR sysexits.h (3)
-error code.
-.\"
-.SH CAVEATS
 
-None of an empty string\(cqs contents pass any of the tests, so the program will
+Str used to have an "isvalue" type as an extension to ctype(3). This was
-exit unsuccessfully if one is specified.
+removed in favor of using strcmp(1) to compare strings against the empty string
+('').
 
-There\(cqs no way of knowing which argument failed the test without re-testing
+.SH BUGS
+
+There's no way of knowing which argument failed the test without re-testing
 arguments individually.
+.PP
+If a character in a string isn't valid ASCII str will exit unsuccessfully.
 
-If a character in a string isn\(cqt valid ASCII, the program will exit
-unsuccessfully.
-.\"
 .SH AUTHOR
 
-Written by DTB
+Written by DTB <trinity@trinity.moe>.
-.MT trinity@trinity.moe
+
-.ME .
-.\"
 .SH COPYRIGHT
 
-Copyright \(co 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
+Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
 <https://gnu.org/licenses/gpl.html>.
-.\"
+
 .SH SEE ALSO
-.BR ctype (3p),
+
-.BR strcmp(1),
+ctype(3p), strcmp(1), ascii(7)
-.BR ascii(7)

docs/strcmp.1

@@ -1,75 +1,62 @@
 .\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe>
-.\" Copyright (c) 2023–2024 Emma Tebibyte <emma@tebibyte.media>
+.\" Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media>
 .\"
 .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
 .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
-.\"
+
-.TH STRCMP 1 2024-06-17 "Harakit X.X.X"
+.TH STRCMP 1
+
 .SH NAME
+
 strcmp \(en compare strings
-.\"
+
 .SH SYNOPSIS
 
 strcmp
-.B string string...
+.RM [ string ]
-.\"
+.RB [ strings... ]
+
 .SH DESCRIPTION
 
-Check whether string arguments are the same.
+Strcmp checks whether the given strings are the same.
-.\"
+Strcmp exits successfully if the strings are identical. Otherwise, strcmp exits
+with the value 1 if an earlier string has a greater byte value than a later
+string (e.g.
+.R strcmp b a
+)
+and 255 if an earlier string has a lesser byte value (e.g.
+.R strcmp a b
+).
+
 .SH DIAGNOSTICS
 
-The program will exit successfully if the strings are identical. Otherwise, it
+Strcmp will print an error message and exit unsuccessfully with a status
-will exit with an error code of 1 if a string passed has a lesser byte value
+described in sysexits(3) if used incorrectly (given less than two operands).
-than one of the prior strings:
 
-.RS
+.SH UNICODE
-strcmp b a
-.RE
 
-or with an error code of 255 if it has a greater byte value than one of the
+Strcmp will exit unsuccessfully if the given strings are not identical;
-prior strings:
+Unicode strings may need to be normalized if the intent is to check visual
+similarity and not byte similarity.
 
-.RS
-strcmp a b
-.RE
-
-When invoked incorrectly, a debug message will be printed and the program will
-exit with the appropriate
-.BR sysexits.h (3)
-error code.
-.\"
-.SH CAVEATS
-
-The program will exit unsuccessfully if the given strings are not identical;
-therefore, Unicode strings may need to be normalized if the intent is to check
-visual similarity and not byte similarity.
-.\"
 .SH RATIONALE
 
 The traditional tool for string comparisons in POSIX and other Unix shells has
-been
+been test(1). This tool also handles integer comparisons and file scrutiny.
-.BR test (1).
+These parts of its functionality have been broken out into multiple utilities.
-This tool also handles integer comparisons and file scrutiny. These parts of its
+
-functionality have been broken out into multiple utilities.
+Strcmp’s functionality may be performed on a POSIX-compliant system with
+test(1p).
 
-This program\(cqs functionality may be performed on a POSIX-compliant system
-with
-.BR test (1p).
-.\"
 .SH AUTHOR
 
-Written by DTB 
+Written by DTB <trinity@trinity.moe>.
-.MT trinity@trinity.moe
+
-.ME .
-.\"
 .SH COPYRIGHT
 
-Copyright \(co 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
+Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
 <https://gnu.org/licenses/gpl.html>.
-.\"
+
 .SH SEE ALSO
-.BR strcmp (3),
+
-.BR intcmp (1),
+strcmp(3), intcmp(1), scrut(1), test(1p)
-.BR scrut (1),
-.BR test (1p)

docs/swab.1

@@ -1,77 +0,0 @@
-.\" Copyright (c) 2024 DTB <trinity@trinity.moe>
-.\" Copyright (c) 2024 Emma Tebibyte <emma@tebibyte.media>
-.\"
-.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
-.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
-.\"
-.TH SWAB 1 2024-06-17 "Harakit X.X.X"
-.SH NAME
-swab \(en swap bytes
-.\"
-.SH SYNOPSIS
-
-swab
-.RB [ -f ]
-.RB [ -w\ word_size ]
-.\"
-.SH DESCRIPTION
-
-Swap the latter and former halves of a block of bytes.
-.\"
-.SH OPTIONS
-
-.IP \fB-f\fP
-Ignore SIGINT signal.
-.IP \fB-w\fP\ \fIword_size\fP
-Configures the word size; that is, the size in bytes of the block size on which
-to operate. The default word size is 2. The word size must be cleanly divisible
-by 2, otherwise the block of bytes being processed can\(cqt be halved.
-.\"
-.SH EXAMPLES
-
-The following
-.BR sh (1p)
-line:
-
-.RS
-printf 'hello world!\(rsn' | swab
-.RE
-
-Produces the following output:
-
-.RS
-ehll oowlr!d
-.RE
-.\"
-.SH DIAGNOSTICS
-
-In the event of an error, a debug message will be printed and the program will
-exit with the appropriate
-.BR sysexits.h (3)
-error code.
-.\"
-.SH RATIONALE
-
-This program was modeled and named after the
-.B conv=swab
-functionality specified
-in the
-.BR dd (1p)
-utility. It additionally allows the word size to be configured.
-
-This functionality is useful for fixing the endianness of binary files produced
-on other machines.
-.\"
-.SH AUTHOR
-
-Written by DTB
-.MT trinity@trinity.moe
-.ME .
-.\"
-.SH COPYRIGHT
-
-Copyright \(co 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
-<https://gnu.org/licenses/agpl.html>.
-.\"
-.SH SEE ALSO
-.BR dd (1p)

docs/true.1

@@ -1,36 +1,35 @@
 .\" Copyright (c) 2022, 2024 DTB <trinity@trinity.moe>
-.\" Copyright (c) 2023–2024 Emma Tebibyte <emma@tebibyte.media>
+.\" Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media>
 .\"
 .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
 .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
-.\"
+
-.TH TRUE 1 2024-06-06 "Harakit X.X.X"
+.TH TRUE 1
+
 .SH NAME
+
 true \(en do nothing, successfully
-.\"
+
 .SH DESCRIPTION
 
-Do nothing regardless of operands or standard input. An exit code of 0 will
+True does nothing regardless of operands or standard input.
-always be returned.
+True will always return an exit code of 0.
-.\"
+
 .SH RATIONALE
 
-In \fIPOSIX.1-2017\fP,
+True exists for the construction of control flow and loops based on a success.
-.BR true (1p)
+
-exists for the construction of control flow and loops based on a success. This
+True functions as described in POSIX.1-2017.
-implementation functions as described in that standard.
+
-.\"
 .SH AUTHOR
 
-Written by Emma Tebibyte
+Written by Emma Tebibyte <emma@tebibyte.media>.
-.MT emma@tebibyte.media
+
-.ME .
-.\"
 .SH COPYRIGHT
 
 This work is marked with CC0 1.0. To see a copy of this license, visit
 <http://creativecommons.org/publicdomain/zero/1.0>.
-.\"
+
 .SH SEE ALSO
-.BR false (1p),
+
-.BR true (1p)
+false(1p)

src/dj.c

@@ -203,28 +203,28 @@ Io_fdseek(struct Io *io){
 	
 	if(!fdisstd(io->fd) && lseek(io->fd, io->seek, SEEK_SET) != -1)
 		return -1;
-
+	else if(io->fl == write_flags){
-	/* repeated code to get the condition out of the loop */
-	if(io->fl == write_flags){
 		memset(io->buf, '\0', io->bs);
-		/* We're going to cheat and use bufuse as the retval for write(2),
+		/* This is a dirty trick; rather than testing conditions and operating
-		 * which is fine because it'll be zeroed as this function returns
+		 * likewise, because the parameters to read or write are going to be
-		 * anyway. */
+		 * the same either way, just use a function pointer to keep track of
-		do{
+		 * the intended operation. */
-			if((io->bufuse = write(io->fd, io->buf, MIN(io->bs, io->seek)))
+		op = (int (*)(int, void *, size_t))&write;
-					== 0)
+		/* Function pointer casts are risky; this works because the difference
-				/* second chance */
+		 * is in the second parameter and only that write(2) makes the buffer
-				io->bufuse = write(io->fd, io->buf, MIN(io->bs, io->seek));
+		 * const whereas read(2) does not. To avoid even the slightest
-		}while((io->seek -= io->bufuse) > 0 && io->bufuse != 0);
+		 * undefined behavior comment out the cast, just be ready for a
-	}else if(io->fl == read_flags){
+		 * -Wincompatible-function-pointer-types if your compiler notices it.
-		do{
+		 */
-			if((io->bufuse = read(io->fd, io->buf, MIN(io->bs, io->seek)))
-					== 0)
-				/* second chance */
-				io->bufuse = read(io->fd, io->buf, MIN(io->bs, io->seek));
-		}while((io->seek -= io->bufuse) > 0 && io->bufuse != 0);
 	}else
-		return EX_SOFTWARE;
+		op = &read;
+
+	/* We're going to cheat and use bufuse as the retval for write(2), which is
+	 * fine because it'll be zeroed as this function returns anyway. */
+	do{	if(	(io->bufuse = (*op)(io->fd, io->buf, MIN(io->bs, io->seek))) == 0)
+			/* second chance */
+			io->bufuse = (*op)(io->fd, io->buf, MIN(io->bs, io->seek));
+	}while((io->seek -= io->bufuse) > 0 && io->bufuse != 0);
 
 	io->bufuse = 0;
 
@@ -313,9 +313,9 @@ parse(char *s){
 static int
 usage(void){
 
-	fprintf(stderr, "Usage: %s [-AdfHqQ] [-a byte] [-c count]\n"
+	fprintf(stderr, "Usage: %s (-AdfHqQ) (-a [byte]) (-c [count])\n"
-		"\t[-i file] [-b block_size] [-s offset]\n"
+		"\t(-i [input file]) (-b [input block size]) (-s [input offset])\n"
-		"\t[-o file] [-B block_size] [-S offset]\n",
+		"\t(-o [output file]) (-B [output block size]) (-S [output offset])\n",
 		program_name);
 
 	return EX_USAGE;

src/fop.rs

@@ -22,54 +22,46 @@ use std::{
 	process::{ Command, exit, Stdio },
 };
 
-extern crate getopt;
-extern crate strerror;
 extern crate sysexits;
+extern crate getopt;
 
-use getopt::GetOpt;
+use getopt::{ Opt, Parser };
-use strerror::StrError;
 use sysexits::{ EX_DATAERR, EX_IOERR, EX_UNAVAILABLE, EX_USAGE };
 
 fn main() {
 	let argv = args().collect::<Vec<String>>();
-	let mut d = '\u{1E}'.to_string();
+	let mut d = '␞';
-	let mut index_arg = 0;
+	let mut arg_parser = Parser::new(&argv, "d:");
 
-	let usage = format!(
+	while let Some(opt) = arg_parser.next() {
-		"Usage: {} [-d delimiter] index command [args...]",
+		match opt {
-		argv[0],
+			Ok(Opt('d', Some(arg))) => {
-	);
+				let arg_char = arg.chars().collect::<Vec<char>>();
-
+				if arg_char.len() > 1 {
-	while let Some(opt) = argv.getopt("d:") {
+					eprintln!("{}: {}: Not a character.", argv[0], arg);
-		match opt.opt() {
+					exit(EX_USAGE);
-			Ok(_) => {
+				} else { d = arg_char[0]; }
-				/* unwrap because Err(OptError::MissingArg) will be returned if
-				 * opt.arg() is None */
-				d = opt.arg().unwrap();
-				index_arg = opt.ind();
 			},
-			Err(_) => {
+			_ => {},
-				eprintln!("{}", usage);
-				exit(EX_USAGE);
-			}
 		};
 	}
 
-	let command_arg = index_arg as usize + 1;
+	let index_arg = arg_parser.index();
+	let command_arg = arg_parser.index() + 1;
 
 	argv.get(command_arg).unwrap_or_else(|| {
-		eprintln!("{}", usage);
+		eprintln!("Usage: {} [-d delimiter] index command [args...]", argv[0]);
 		exit(EX_USAGE);
 	});
 
 	let index = argv[index_arg].parse::<usize>().unwrap_or_else(|e| {
-		eprintln!("{}: {}: {}", argv[0], argv[1], e);
+		eprintln!("{}: {}: {}.", argv[0], argv[1], e);
 		exit(EX_DATAERR);
 	});
 
 	let mut buf = String::new();
 	let _ = stdin().read_to_string(&mut buf);
-	let mut fields = buf.split(&d).collect::<Vec<&str>>();
+	let mut fields = buf.split(d).collect::<Vec<&str>>();
 
 	let opts = argv
 		.iter()
@@ -83,13 +75,13 @@ fn main() {
 		.stdout(Stdio::piped())
 		.spawn()
 		.unwrap_or_else( |e| {
-			eprintln!("{}: {}: {}", argv[0], argv[command_arg], e.strerror());
+			eprintln!("{}: {}: {}.", argv[0], argv[command_arg], e);
 			exit(EX_UNAVAILABLE);
 		});
 
 	let field = fields.get(index).unwrap_or_else(|| {
 		eprintln!(
-			"{}: {}: No such index in input",
+			"{}: {}: No such index in input.",
 			argv[0],
 			index.to_string(),
 		);
@@ -102,7 +94,7 @@ fn main() {
 	}
 
 	let output = spawned.wait_with_output().unwrap_or_else(|e| {
-		eprintln!("{}: {}: {}", argv[0], argv[command_arg], e.strerror());
+		eprintln!("{}: {}: {}.", argv[0], argv[command_arg], e);
 		exit(EX_IOERR);
 	});
 
@@ -111,7 +103,7 @@ fn main() {
 	if replace.pop() != Some(b'\n') { replace = output.stdout; }
 
 	let new_field = String::from_utf8(replace).unwrap_or_else(|e| {
-		eprintln!("{}: {}: {}", argv[0], argv[command_arg], e);
+		eprintln!("{}: {}: {}.", argv[0], argv[command_arg], e);
 		exit(EX_IOERR);
 	});
 
@@ -119,8 +111,8 @@ fn main() {
 
 	stdout().write_all(
 		fields.join(&d.to_string()).as_bytes()
-	).unwrap_or_else(|e| {
+	).unwrap_or_else(|e|{
-		eprintln!("{}: {}", argv[0], e.strerror());
+		eprintln!("{}: {}.", argv[0], e);
 		exit(EX_IOERR);
 	});
 }

src/getopt-rs/error.rs

@@ -0,0 +1,95 @@
+/*
+ * Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ *
+ * This program is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU Affero General Public License as published by the Free
+ * Software Foundation, either version 3 of the License, or (at your option) any
+ * later version.
+ * 
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see https://www.gnu.org/licenses/.
+ *
+ * This file incorporates work covered by the following copyright and permission
+ * notice:
+ *     The Clear BSD License
+ *
+ *     Copyright © 2017-2023 David Wildasin
+ *     All rights reserved.
+ *
+ *     Redistribution and use in source and binary forms, with or without
+ *     modification, are permitted (subject to the limitations in the disclaimer
+ *     below) provided that the following conditions are met:
+ *
+ *          * Redistributions of source code must retain the above copyright
+ *          notice, this list of conditions, and the following disclaimer.
+ *
+ *          * Redistributions in binary form must reproduce the above copyright
+ *          notice, this list of conditions, and the following disclaimer in the
+ *          documentation and/or other materials provided with the distribution.
+ *
+ *          * Neither the name of the copyright holder nor the names of its
+ *          contributors may be used to endorse or promote products derived from
+ *          this software without specific prior written permission.
+ *
+ *     NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED
+ *     BY THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+ *     CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
+ *     BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+ *     FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ *     HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ *     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+ *     TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ *     PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ *     LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ *     NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ *     SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+use std::{ error, fmt };
+
+use crate::ErrorKind::{ self, * };
+
+/// A basic error type for [`Parser`](struct.Parser.html)
+#[derive(Debug, Eq, PartialEq)]
+pub struct Error {
+    culprit: char,
+    kind: ErrorKind,
+}
+
+impl Error {
+    /// Creates a new error using a known kind and the character that caused the
+	/// issue.
+    pub fn new(kind: ErrorKind, culprit: char) -> Self {
+        Self { culprit, kind }
+    }
+
+    /// Returns the [`ErrorKind`](enum.ErrorKind.html) for this error.
+    pub fn kind(self) -> ErrorKind {
+        self.kind
+    }
+}
+
+impl fmt::Display for Error {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        match self.kind {
+            MissingArgument => write!(
+				f, 
+				"option requires an argument -- {:?}",
+				self.culprit,
+			),
+            UnknownOption => write!(f, "unknown option -- {:?}", self.culprit),
+        }
+    }
+}
+
+impl error::Error for Error {
+    fn source(&self) -> Option<&(dyn error::Error + 'static)> {
+        None
+    }
+}

src/getopt-rs/errorkind.rs

@@ -0,0 +1,61 @@
+/*
+ * Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ *
+ * This program is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU Affero General Public License as published by the Free
+ * Software Foundation, either version 3 of the License, or (at your option) any
+ * later version.
+ * 
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see https://www.gnu.org/licenses/.
+ *
+ * This file incorporates work covered by the following copyright and permission
+ * notice:
+ *     The Clear BSD License
+ *
+ *     Copyright © 2017-2023 David Wildasin
+ *     All rights reserved.
+ *
+ *     Redistribution and use in source and binary forms, with or without
+ *     modification, are permitted (subject to the limitations in the disclaimer
+ *     below) provided that the following conditions are met:
+ *
+ *          * Redistributions of source code must retain the above copyright
+ *          notice, this list of conditions, and the following disclaimer.
+ *
+ *          * Redistributions in binary form must reproduce the above copyright
+ *          notice, this list of conditions, and the following disclaimer in the
+ *          documentation and/or other materials provided with the distribution.
+ *
+ *          * Neither the name of the copyright holder nor the names of its
+ *          contributors may be used to endorse or promote products derived from
+ *          this software without specific prior written permission.
+ *
+ *     NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED
+ *     BY THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+ *     CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
+ *     BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+ *     FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ *     HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ *     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+ *     TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ *     PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ *     LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ *     NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ *     SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/// What kinds of errors [`Parser`](struct.Parser.html) can return.
+#[derive(Debug, Eq, PartialEq)]
+pub enum ErrorKind {
+    /// An argument was not found for an option that was expecting one.
+    MissingArgument,
+    /// An unknown option character was encountered.
+    UnknownOption,
+}

src/getopt-rs/lib.rs

@@ -0,0 +1,72 @@
+/*
+ * Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ *
+ * This program is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU Affero General Public License as published by the Free
+ * Software Foundation, either version 3 of the License, or (at your option) any
+ * later version.
+ * 
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see https://www.gnu.org/licenses/.
+ *
+ * This file incorporates work covered by the following copyright and permission
+ * notice:
+ *     The Clear BSD License
+ *
+ *     Copyright © 2017-2023 David Wildasin
+ *     All rights reserved.
+ *
+ *     Redistribution and use in source and binary forms, with or without
+ *     modification, are permitted (subject to the limitations in the disclaimer
+ *     below) provided that the following conditions are met:
+ *
+ *          * Redistributions of source code must retain the above copyright
+ *          notice, this list of conditions, and the following disclaimer.
+ *
+ *          * Redistributions in binary form must reproduce the above copyright
+ *          notice, this list of conditions, and the following disclaimer in the
+ *          documentation and/or other materials provided with the distribution.
+ *
+ *          * Neither the name of the copyright holder nor the names of its
+ *          contributors may be used to endorse or promote products derived from
+ *          this software without specific prior written permission.
+ *
+ *     NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED
+ *     BY THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+ *     CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
+ *     BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+ *     FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ *     HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ *     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+ *     TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ *     PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ *     LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ *     NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ *     SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+//! # getopt
+//!
+//! `getopt` provides a minimal, (essentially) POSIX-compliant option parser.
+
+pub use crate::{
+	error::Error,
+	errorkind::ErrorKind,
+	opt::Opt,
+	parser::Parser,
+	result::Result
+};
+
+mod error;
+mod errorkind;
+mod opt;
+mod parser;
+mod result;
+#[cfg(test)]
+mod tests;

src/getopt-rs/opt.rs

@@ -0,0 +1,89 @@
+/*
+ * Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ *
+ * This program is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU Affero General Public License as published by the Free
+ * Software Foundation, either version 3 of the License, or (at your option) any
+ * later version.
+ * 
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see https://www.gnu.org/licenses/.
+ *
+ * This file incorporates work covered by the following copyright and permission
+ * notice:
+ *     The Clear BSD License
+ *
+ *     Copyright © 2017-2023 David Wildasin
+ *     All rights reserved.
+ *
+ *     Redistribution and use in source and binary forms, with or without
+ *     modification, are permitted (subject to the limitations in the disclaimer
+ *     below) provided that the following conditions are met:
+ *
+ *          * Redistributions of source code must retain the above copyright
+ *          notice, this list of conditions, and the following disclaimer.
+ *
+ *          * Redistributions in binary form must reproduce the above copyright
+ *          notice, this list of conditions, and the following disclaimer in the
+ *          documentation and/or other materials provided with the distribution.
+ *
+ *          * Neither the name of the copyright holder nor the names of its
+ *          contributors may be used to endorse or promote products derived from
+ *          this software without specific prior written permission.
+ *
+ *     NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED
+ *     BY THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+ *     CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
+ *     BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+ *     FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ *     HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ *     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+ *     TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ *     PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ *     LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ *     NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ *     SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+use std::fmt;
+
+/// A single option.
+///
+/// For `Opt(x, y)`:
+///   - `x` is the character representing the option.
+///   - `y` is `Some` string, or `None` if no argument was expected.
+///
+/// # Example
+///
+/// ```
+/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
+/// use getopt::Opt;
+///
+/// // args = ["program", "-abc", "foo"];
+/// # let args: Vec<String> = vec!["program", "-abc", "foo"]
+/// #     .into_iter()
+/// #     .map(String::from)
+/// #     .collect();
+/// let optstring = "ab:c";
+/// let mut opts = getopt::Parser::new(&args, optstring);
+///
+/// assert_eq!(Opt('a', None), opts.next().transpose()?.unwrap());
+/// assert_eq!(Opt('b', Some("c".to_string())), opts.next().transpose()?.unwrap());
+/// assert_eq!(None, opts.next().transpose()?);
+/// # Ok(())
+/// # }
+/// ```
+#[derive(Debug, Eq, Ord, PartialEq, PartialOrd)]
+pub struct Opt(pub char, pub Option<String>);
+
+impl fmt::Display for Opt {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(f, "Opt({:?}, {:?})", self.0, self.1)
+    }
+}

src/getopt-rs/parser.rs

@@ -0,0 +1,382 @@
+/*
+ * Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ *
+ * This program is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU Affero General Public License as published by the Free
+ * Software Foundation, either version 3 of the License, or (at your option) any
+ * later version.
+ * 
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see https://www.gnu.org/licenses/.
+ *
+ * This file incorporates work covered by the following copyright and permission
+ * notice:
+ *     The Clear BSD License
+ *
+ *     Copyright © 2017-2023 David Wildasin
+ *     All rights reserved.
+ *
+ *     Redistribution and use in source and binary forms, with or without
+ *     modification, are permitted (subject to the limitations in the disclaimer
+ *     below) provided that the following conditions are met:
+ *
+ *          * Redistributions of source code must retain the above copyright
+ *          notice, this list of conditions, and the following disclaimer.
+ *
+ *          * Redistributions in binary form must reproduce the above copyright
+ *          notice, this list of conditions, and the following disclaimer in the
+ *          documentation and/or other materials provided with the distribution.
+ *
+ *          * Neither the name of the copyright holder nor the names of its
+ *          contributors may be used to endorse or promote products derived from
+ *          this software without specific prior written permission.
+ *
+ *     NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED
+ *     BY THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+ *     CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
+ *     BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+ *     FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ *     HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ *     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+ *     TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ *     PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ *     LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ *     NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ *     SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+use std::collections::HashMap;
+
+use crate::{ error::Error, errorkind::ErrorKind, opt::Opt, result::Result };
+
+/// The core of the `getopt` crate.
+///
+/// `Parser` is implemented as an iterator over the options present in the given
+/// argument vector.
+///
+/// The method [`next`](#method.next) does the heavy lifting.
+///
+/// # Examples
+///
+/// ## Simplified usage:
+/// ```
+/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
+/// use getopt::Opt;
+///
+/// // args = ["program", "-abc", "foo"];
+/// # let args: Vec<String> = vec!["program", "-abc", "foo"]
+/// #     .into_iter()
+/// #     .map(String::from)
+/// #     .collect();
+/// let mut opts = getopt::Parser::new(&args, "ab:c");
+///
+/// assert_eq!(Some(Opt('a', None)), opts.next().transpose()?);
+/// assert_eq!(1, opts.index());
+/// assert_eq!(Some(Opt('b', Some("c".to_string()))), opts.next().transpose()?);
+/// assert_eq!(2, opts.index());
+/// assert_eq!(None, opts.next());
+/// assert_eq!(2, opts.index());
+/// assert_eq!("foo", args[opts.index()]);
+/// # Ok(())
+/// # }
+/// ```
+///
+/// ## A more idiomatic example:
+/// ```
+/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
+/// use getopt::Opt;
+///
+/// // args = ["program", "-abc", "-d", "foo", "-e", "bar"];
+/// # let mut args: Vec<String> = vec!["program", "-abc", "-d", "foo", "-e", "bar"]
+/// #     .into_iter()
+/// #     .map(String::from)
+/// #     .collect();
+/// let mut opts = getopt::Parser::new(&args, "ab:cd:e");
+///
+/// let mut a_flag = false;
+/// let mut b_flag = String::new();
+/// let mut c_flag = false;
+/// let mut d_flag = String::new();
+/// let mut e_flag = false;
+///
+/// loop {
+///     match opts.next().transpose()? {
+///         None => break,
+///         Some(opt) => match opt {
+///             Opt('a', None) => a_flag = true,
+///             Opt('b', Some(arg)) => b_flag = arg.clone(),
+///             Opt('c', None) => c_flag = true,
+///             Opt('d', Some(arg)) => d_flag = arg.clone(),
+///             Opt('e', None) => e_flag = true,
+///             _ => unreachable!(),
+///         },
+///     }
+/// }
+///
+/// let new_args = args.split_off(opts.index());
+///
+/// assert_eq!(true, a_flag);
+/// assert_eq!("c", b_flag);
+/// assert_eq!(false, c_flag);
+/// assert_eq!("foo", d_flag);
+/// assert_eq!(true, e_flag);
+///
+/// assert_eq!(1, new_args.len());
+/// assert_eq!("bar", new_args.first().unwrap());
+/// # Ok(())
+/// # }
+/// ```
+#[derive(Debug, Eq, PartialEq)]
+pub struct Parser {
+    opts: HashMap<char, bool>,
+    args: Vec<Vec<char>>,
+    index: usize,
+    point: usize,
+}
+
+impl Parser {
+    /// Create a new `Parser`, which will process the arguments in `args`
+	/// according to the options specified in `optstring`.
+    ///
+    /// For compatibility with
+	/// [`std::env::args`](https://doc.rust-lang.org/std/env/fn.args.html),
+    /// valid options are expected to begin at the second element of `args`, and
+	/// `index` is
+    /// initialised to `1`.
+    /// If `args` is structured differently, be sure to call
+	/// [`set_index`](#method.set_index) before the first invocation of
+	/// [`next`](#method.next).
+    ///
+    /// `optstring` is a string of recognised option characters; if a character
+	/// is followed by a colon (`:`), that option takes an argument.
+    ///
+    /// # Note:
+    /// Transforming the OS-specific argument strings into a vector of `String`s
+	/// is the sole responsibility of the calling program, as it involves some
+	/// level of potential information loss (which this crate does not presume
+	/// to handle unilaterally) and error handling (which would complicate the
+	/// interface).
+    pub fn new(args: &[String], optstring: &str) -> Self {
+        let optstring: Vec<char> = optstring.chars().collect();
+        let mut opts = HashMap::new();
+        let mut i = 0;
+        let len = optstring.len();
+
+        while i < len {
+            let j = i + 1;
+
+            if j < len && optstring[j] == ':' {
+                opts.insert(optstring[i], true);
+                i += 1;
+            } else {
+                opts.insert(optstring[i], false);
+            }
+            i += 1;
+        }
+
+        Self {
+            opts,
+            // "explode" the args into a vector of character vectors, to allow
+			// indexing
+            args: args.iter().map(|e| e.chars().collect()).collect(),
+            index: 1,
+            point: 0,
+        }
+    }
+
+    /// Return the current `index` of the parser.
+    ///
+    /// `args[index]` will always point to the the next element of `args`; when
+	/// the parser is
+    /// finished with an element, it will increment `index`.
+    ///
+    /// After the last option has been parsed (and [`next`](#method.next) is
+	/// returning `None`),
+    /// `index` will point to the first non-option argument.
+    pub fn index(&self) -> usize {
+        self.index
+    }
+
+    // `point` must be reset to 0 whenever `index` is changed
+
+    /// Modify the current `index` of the parser.
+    pub fn set_index(&mut self, value: usize) {
+        self.index = value;
+        self.point = 0;
+    }
+
+    /// Increment the current `index` of the parser.
+    ///
+    /// This use case is common enough to warrant its own optimised method.
+    pub fn incr_index(&mut self) {
+        self.index += 1;
+        self.point = 0;
+    }
+}
+
+impl Iterator for Parser {
+    type Item = Result<Opt>;
+
+    /// Returns the next option, if any.
+    ///
+    /// Returns an [`Error`](struct.Error.html) if an unexpected option is
+	/// encountered or if an
+    /// expected argument is not found.
+    ///
+    /// Parsing stops at the first non-hyphenated argument; or at the first
+	/// argument matching "-";
+    /// or after the first argument matching "--".
+    ///
+    /// When no more options are available, `next` returns `None`.
+    ///
+    /// # Examples
+    ///
+    /// ## "-"
+    /// ```
+    /// use getopt::Parser;
+    ///
+    /// // args = ["program", "-", "-a"];
+    /// # let args: Vec<String> = vec!["program", "-", "-a"]
+    /// #     .into_iter()
+    /// #     .map(String::from)
+    /// #     .collect();
+    /// let mut opts = Parser::new(&args, "a");
+    ///
+    /// assert_eq!(None, opts.next());
+    /// assert_eq!("-", args[opts.index()]);
+    /// ```
+    ///
+    /// ## "--"
+    /// ```
+    /// use getopt::Parser;
+    ///
+    /// // args = ["program", "--", "-a"];
+    /// # let args: Vec<String> = vec!["program", "--", "-a"]
+    /// #     .into_iter()
+    /// #     .map(String::from)
+    /// #     .collect();
+    /// let mut opts = Parser::new(&args, "a");
+    ///
+    /// assert_eq!(None, opts.next());
+    /// assert_eq!("-a", args[opts.index()]);
+    /// ```
+    ///
+    /// ## Unexpected option:
+    /// ```
+    /// use getopt::Parser;
+    ///
+    /// // args = ["program", "-b"];
+    /// # let args: Vec<String> = vec!["program", "-b"]
+    /// #     .into_iter()
+    /// #     .map(String::from)
+    /// #     .collect();
+    /// let mut opts = Parser::new(&args, "a");
+    ///
+    /// assert_eq!(
+    ///     "unknown option -- 'b'".to_string(),
+    ///     opts.next().unwrap().unwrap_err().to_string()
+    /// );
+    /// ```
+    ///
+    /// ## Missing argument:
+    /// ```
+    /// use getopt::Parser;
+    ///
+    /// // args = ["program", "-a"];
+    /// # let args: Vec<String> = vec!["program", "-a"]
+    /// #     .into_iter()
+    /// #     .map(String::from)
+    /// #     .collect();
+    /// let mut opts = Parser::new(&args, "a:");
+    ///
+    /// assert_eq!(
+    ///     "option requires an argument -- 'a'".to_string(),
+    ///     opts.next().unwrap().unwrap_err().to_string()
+    /// );
+    /// ```
+    fn next(&mut self) -> Option<Result<Opt>> {
+        if self.point == 0 {
+            /*
+             * Rationale excerpts below taken verbatim from "The Open Group Base
+			 * Specifications Issue 7, 2018 edition", IEEE Std 1003.1-2017
+			 * (Revision of IEEE Std 1003.1-2008).
+             * Copyright © 2001-2018 IEEE and The Open Group.
+             */
+
+            /*
+             * If, when getopt() is called:
+             *      argv[optind]    is a null pointer
+             *      *argv[optind]   is not the character '-'
+             *      argv[optind]    points to the string "-"
+             * getopt() shall return -1 without changing optind.
+             */
+            if self.index >= self.args.len()
+                || self.args[self.index].is_empty()
+                || self.args[self.index][0] != '-'
+                || self.args[self.index].len() == 1
+            {
+                return None;
+            }
+
+            /*
+             * If:
+             *      argv[optind]    points to the string "--"
+             * getopt() shall return -1 after incrementing index.
+             */
+            if self.args[self.index][1] == '-' && self.args[self.index].len() == 2 {
+                self.incr_index();
+                return None;
+            }
+
+            // move past the starting '-'
+            self.point += 1;
+        }
+
+        let opt = self.args[self.index][self.point];
+        self.point += 1;
+
+        match self.opts.get(&opt) {
+            None => {
+                if self.point >= self.args[self.index].len() {
+                    self.incr_index();
+                }
+                Some(Err(Error::new(ErrorKind::UnknownOption, opt)))
+            }
+            Some(false) => {
+                if self.point >= self.args[self.index].len() {
+                    self.incr_index();
+                }
+
+                Some(Ok(Opt(opt, None)))
+            }
+            Some(true) => {
+                let arg: String = if self.point >= self.args[self.index].len() {
+                    self.incr_index();
+                    if self.index >= self.args.len() {
+                        return Some(Err(Error::new(
+									ErrorKind::MissingArgument,
+									opt,
+								)));
+                    }
+                    self.args[self.index].iter().collect()
+                } else {
+                    self.args[self.index]
+                        .clone()
+                        .split_off(self.point)
+                        .iter()
+                        .collect()
+                };
+
+                self.incr_index();
+
+                Some(Ok(Opt(opt, Some(arg))))
+            }
+        }
+    }
+}

src/getopt-rs/result.rs

@@ -0,0 +1,59 @@
+/*
+ * Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ *
+ * This program is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU Affero General Public License as published by the Free
+ * Software Foundation, either version 3 of the License, or (at your option) any
+ * later version.
+ * 
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see https://www.gnu.org/licenses/.
+ *
+ * This file incorporates work covered by the following copyright and permission
+ * notice:
+ *     The Clear BSD License
+ *
+ *     Copyright © 2017-2023 David Wildasin
+ *     All rights reserved.
+ *
+ *     Redistribution and use in source and binary forms, with or without
+ *     modification, are permitted (subject to the limitations in the disclaimer
+ *     below) provided that the following conditions are met:
+ *
+ *          * Redistributions of source code must retain the above copyright
+ *          notice, this list of conditions, and the following disclaimer.
+ *
+ *          * Redistributions in binary form must reproduce the above copyright
+ *          notice, this list of conditions, and the following disclaimer in the
+ *          documentation and/or other materials provided with the distribution.
+ *
+ *          * Neither the name of the copyright holder nor the names of its
+ *          contributors may be used to endorse or promote products derived from
+ *          this software without specific prior written permission.
+ *
+ *     NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED
+ *     BY THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+ *     CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
+ *     BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+ *     FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ *     HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ *     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+ *     TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ *     PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ *     LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ *     NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ *     SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+use std::result;
+
+use crate::error::Error;
+
+/// A specialized `Result` type for use with [`Parser`](struct.Parser.html)
+pub type Result<T> = result::Result<T, Error>;

src/getopt-rs/tests.rs

@@ -0,0 +1,228 @@
+/*
+ * Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ *
+ * This program is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU Affero General Public License as published by the Free
+ * Software Foundation, either version 3 of the License, or (at your option) any
+ * later version.
+ * 
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see https://www.gnu.org/licenses/.
+ *
+ * This file incorporates work covered by the following copyright and permission
+ * notice:
+ *     The Clear BSD License
+ *
+ *     Copyright © 2017-2023 David Wildasin
+ *     All rights reserved.
+ *
+ *     Redistribution and use in source and binary forms, with or without
+ *     modification, are permitted (subject to the limitations in the disclaimer
+ *     below) provided that the following conditions are met:
+ *
+ *          * Redistributions of source code must retain the above copyright
+ *          notice, this list of conditions, and the following disclaimer.
+ *
+ *          * Redistributions in binary form must reproduce the above copyright
+ *          notice, this list of conditions, and the following disclaimer in the
+ *          documentation and/or other materials provided with the distribution.
+ *
+ *          * Neither the name of the copyright holder nor the names of its
+ *          contributors may be used to endorse or promote products derived from
+ *          this software without specific prior written permission.
+ *
+ *     NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED
+ *     BY THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+ *     CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
+ *     BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+ *     FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ *     HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ *     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+ *     TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ *     PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ *     LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ *     NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ *     SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+use crate::{Opt, Parser};
+
+macro_rules! basic_test {
+    ($name:ident, $expect:expr, $next:expr, [$($arg:expr),+], $optstr:expr) => (
+        #[test]
+        fn $name() -> Result<(), String> {
+            let expect: Option<Opt> = $expect;
+            let args: Vec<String> = vec![$($arg),+]
+				.into_iter()
+				.map(String::from)
+				.collect();
+            let next: Option<String> = $next;
+            let mut opts = Parser::new(&args, $optstr);
+
+            match opts.next().transpose() {
+                Err(error) => {
+                    return Err(format!("next() returned {:?}", error))
+                },
+                Ok(actual) => if actual != expect {
+                    return Err(
+						format!("expected {:?}; got {:?}", expect, actual)
+					)
+                },
+            };
+
+            match next {
+                None => if opts.index() < args.len() {
+                    return Err(format!(
+							"expected end of args; got {:?}", args[opts.index()]
+					))
+                },
+                Some(n) => if args[opts.index()] != n {
+                    return Err(format!(
+							"next arg: expected {:?}; got {:?}",
+							n,
+							args[opts.index()]
+					))
+                },
+            };
+
+            Ok(())
+        }
+    )
+}
+
+#[rustfmt::skip] basic_test!(
+	blank_arg, None, Some(String::new()), ["x", ""], "a"
+);
+#[rustfmt::skip] basic_test!(
+	double_dash, None, Some("-a".to_string()), ["x", "--", "-a", "foo"], "a"
+);
+#[rustfmt::skip] basic_test!(no_opts_1, None, None, ["x"], "a");
+#[rustfmt::skip] basic_test!(
+	no_opts_2, None, Some("foo".to_string()), ["x", "foo"], "a"
+);
+#[rustfmt::skip] basic_test!(
+	no_opts_3, None, Some("foo".to_string()), ["x", "foo", "-a"], "a"
+);
+#[rustfmt::skip] basic_test!(
+	single_dash, None, Some("-".to_string()), ["x", "-", "-a", "foo"], "a"
+);
+#[rustfmt::skip] basic_test!(
+	single_opt,
+	Some(Opt('a', None)),
+	Some("foo".to_string()),
+	["x", "-a", "foo"],
+	"a"
+);
+#[rustfmt::skip] basic_test!(
+	single_optarg,
+	Some(Opt('a', Some("foo".to_string()))),
+	None,
+	["x", "-a", "foo"],
+	"a:"
+);
+
+macro_rules! error_test {
+    ($name:ident, $expect:expr, [$($arg:expr),+], $optstr:expr) => (
+        #[test]
+        fn $name() -> Result<(), String> {
+            let expect: String = $expect.to_string();
+            let args: Vec<String> = vec![$($arg),+]
+				.into_iter()
+				.map(String::from)
+				.collect();
+            let mut opts = Parser::new(&args, $optstr);
+
+            match opts.next() {
+                None => {
+                    return Err(format!(
+							"unexpected successful response: end of options"
+					))
+                },
+                Some(Err(actual)) => {
+                    let actual = actual.to_string();
+
+                    if actual != expect {
+                        return Err(
+							format!("expected {:?}; got {:?}", expect, actual)
+						);
+                    }
+                },
+                Some(Ok(opt)) => {
+                    return Err(
+						format!("unexpected successful response: {:?}", opt)
+					)
+                },
+            };
+
+            Ok(())
+        }
+    )
+}
+
+#[rustfmt::skip] error_test!(
+	bad_opt,
+	"unknown option -- 'b'",
+	["x", "-b"],
+	"a"
+);
+
+#[rustfmt::skip] error_test!(
+	missing_optarg,
+	"option requires an argument -- 'a'",
+	["x", "-a"],
+	"a:"
+);
+
+#[test]
+fn multiple() -> Result<(), String> {
+    let args: Vec<String> = vec!["x", "-abc", "-d", "foo", "-e", "bar"]
+        .into_iter()
+        .map(String::from)
+        .collect();
+    let optstring = "ab:d:e".to_string();
+    let mut opts = Parser::new(&args, &optstring);
+
+    macro_rules! check_result {
+        ($expect:expr) => {
+            let expect: Option<Opt> = $expect;
+            match opts.next().transpose() {
+                Err(error) => {
+					return Err(format!("next() returned {:?}", error));
+				},
+                Ok(actual) => {
+                    if actual != expect {
+                        return Err(
+							format!("expected {:?}; got {:?}", expect, actual)
+						);
+                    }
+                }
+            };
+        };
+    }
+
+    check_result!(Some(Opt('a', None)));
+    check_result!(Some(Opt('b', Some("c".to_string()))));
+    check_result!(Some(Opt('d', Some("foo".to_string()))));
+    check_result!(Some(Opt('e', None)));
+    check_result!(None);
+
+    Ok(())
+}
+
+#[test]
+fn continue_after_error() {
+    let args: Vec<String> = vec!["x", "-z", "-abc"]
+        .into_iter()
+        .map(String::from)
+        .collect();
+    let optstring = "ab:d:e".to_string();
+    for _opt in Parser::new(&args, &optstring) {
+        // do nothing, should not panic
+    }
+}

src/hru.rs

@@ -23,10 +23,8 @@ use std::{
 	process::{ ExitCode, exit },
 };
 
-extern crate strerror;
 extern crate sysexits;
 
-use strerror::StrError;
 use sysexits::{ EX_DATAERR, EX_IOERR, EX_SOFTWARE };
 
 const LIST: [(u32, &str); 10] = [
@@ -51,7 +49,7 @@ fn convert(input: u128) -> Result<(f64, (u32, &'static str)), String> {
 		let c = match 10_u128.checked_pow(n) {
 			Some(c) => c,
 			None => {
-				return Err(format!("10^{}: Integer overflow", n.to_string()));
+				return Err(format!("10^{}: Integer overflow.", n.to_string()));
 			},
 		};
 
@@ -81,7 +79,7 @@ fn main() -> ExitCode {
 				f
 			},
 			Err(err) => {
-				eprintln!("{}: {}", argv[0], err);
+				eprintln!("{}: {}.", argv[0], err);
 				return ExitCode::from(EX_DATAERR as u8);
 			},
 		};
@@ -89,7 +87,7 @@ fn main() -> ExitCode {
 		let (number, prefix) = match convert(n) {
 			Ok(x) => x,
 			Err(err) => {
-				eprintln!("{}: {}", argv[0], err);
+				eprintln!("{}: {}.", argv[0], err);
 				return ExitCode::from(EX_SOFTWARE as u8);
 			},
 		};
@@ -100,7 +98,7 @@ fn main() -> ExitCode {
 
 		stdout().write_all(format!("{} {}\n", out, si_prefix).as_bytes())
 			.unwrap_or_else(|e| {
-				eprintln!("{}: {}", argv[0], e.strerror());
+				eprintln!("{}: {}.", argv[0], e);
 				exit(EX_IOERR);
 			});
 	}

src/intcmp.c

@@ -52,7 +52,7 @@ int main(int argc, char *argv[]){
 
 	if(optind + 2 /* ref cmp */ > argc){
 usage:		fprintf(stderr,
-			"Usage: %s [-egl] integer integer...\n",
+			"Usage: %s (-eghl) [integer] [integer...]\n",
 			argv[0] == NULL ? program_name : argv[0]);
 		return EX_USAGE;
 	}

src/libgetopt.rs

@@ -1,202 +0,0 @@
-/*
- * Copyright (c) 2023–2024 Emma Tebibyte <emma@tebibyte.media>
- * SPDX-License-Identifier: AGPL-3.0-or-later
- *
- * This program is free software: you can redistribute it and/or modify it under
- * the terms of the GNU Affero General Public License as published by the Free
- * Software Foundation, either version 3 of the License, or (at your option) any
- * later version.
- * 
- * This program is distributed in the hope that it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
- * FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
- * details.
- *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program. If not, see https://www.gnu.org/licenses/.
- */
-
-use std::ffi::{ c_int, c_char, CString, CStr };
-
-/* binding to getopt(3p) */
-extern "C" {
-	static mut optarg: *mut c_char;
-	static mut _opterr: c_int;
-	static mut optind: c_int;
-	static mut optopt: c_int;
-
-	fn getopt(
-		___argc: c_int,
-		___argv: *const *mut c_char,
-		__shortopts: *const c_char,
-	) -> c_int;
-}
-
-#[derive(Clone, Debug)]
-pub enum OptError {
-	MissingArg(String),
-	UnknownOpt(String),
-}
-
-#[derive(Clone, Debug)]
-pub struct Opt {
-	arg: Option<String>, /* option argument */
-	ind: *mut i32, /* option index */
-	opt: Result<String, OptError>, /* option option */
-}
-
-impl Opt {
-	pub fn arg(&self) -> Option<String> { self.arg.clone() }
-
-	/* sets optarg if default is desired */
-	pub fn arg_or(&self, default: impl std::fmt::Display) -> String {
-		default.to_string()
-	}
-
-	/* makes matching the output of this method more bearable */
-	pub fn opt(&self) -> Result<&str, OptError> {
-		self.opt.as_ref().map(|o| o.as_str()).map_err(OptError::clone)
-	}
-
-	/* From getopt(3p):
-	 *
-	 * The variable optind is the index of the next element of the argv[]
-	 * vector to be processed. It shall be initialized to 1 by the system, and
-	 * getopt() shall update it when it finishes with each element of argv[].
-	 * If the application sets optind to zero  before calling getopt(), the
-	 * behavior is unspecified. When an element of argv[] contains multiple
-	 * option characters, it is unspecified how getopt() determines which
-	 * options have already been processed. */
-	pub fn ind(&self) -> usize { unsafe { *self.ind as usize } }
-
-	/* this is patently terrible and is only happening because I’m stubborn */
-	pub fn set_ind(&self, ind: i32) { unsafe { *self.ind = ind; } }
-}
-
-/* function signature */
-pub trait GetOpt {
-	fn getopt(&self, optstring: &str) -> Option<Opt>;
-}
-
-impl GetOpt for Vec<String> {
-    fn getopt(&self, optstring: &str) -> Option<Opt> {
-        let c_strings: Vec<_> = self
-			.iter()
-			.cloned()
-			.map(|x| CString::new(x).unwrap().into_raw())
-			.collect();
-
-		/* god knows what this does */
-		let boxed = Box::into_raw(c_strings.into_boxed_slice());
-		let argv = boxed as *const *mut c_char;
-
-		/* operations are separated out so that everything lives long enough */
-        let opts = CString::new(optstring).unwrap().into_raw();
-        let len = self.len() as c_int;
-
-        unsafe {
-            let ret = match getopt(len, argv, opts) { 
-				/* From getopt(3p):
-				 *
-				 * The getopt() function shall return the next option character
-				 * specified on the command line.
-				 *
-				 * A <colon> (':') shall be returned if getopt() detects a
-				 * missing argument and the first character of optstring was a
-				 * <colon> (':').
-				 *
-				 * A <question-mark> ('?') shall be returned if getopt()
-				 * encounters an option character not in optstring or detects a
-				 * missing argument and the first character of optstring was not
-				 * a <colon> (':').
-				 *
-				 * Otherwise, getopt() shall return -1 when all command line
-				 * options are parsed. */
-				58 => { /* ASCII ':' */
-					Some(Opt {
-						arg: None,
-						ind: std::ptr::addr_of_mut!(optind),
-						/* error containing option */
-						opt: Err(OptError::MissingArg(optopt.to_string())),
-					})
-				},
-				63 => { /* ASCII '?' */
-					Some(Opt {
-						arg: None,
-						ind: std::ptr::addr_of_mut!(optind),
-						/* error containing option */
-						opt: Err(OptError::UnknownOpt(optopt.to_string())),
-					})
-				},
-				/* From getopt(3p):
-				 *
-				 * If, when getopt() is called:
-				 *
-				 * argv[optind]  is a null pointer
-				 * *argv[optind]  is not the character -
-				 * argv[optind]  points to the string "-"
-				 *
-				 * getopt() shall return -1 without changing optind.  If:
-				 *
-				 * argv[optind]   points to the string "--"
-				 *
-				 * getopt() shall return -1 after incrementing optind. */
-                -1 => return None,
-                opt => {
-					let arg: Option<String>;
-
-					if optarg.is_null() { arg = None; }
-					else {
-						arg = Some(CStr::from_ptr(optarg)
-							.to_string_lossy()
-							.into_owned());
-					}
-
-					Some(Opt {
-						arg,
-						ind: std::ptr::addr_of_mut!(optind),
-						/* I didn’t need to cast this before; I rewrote the
-						 * pointer logic and now I do
-						 *
-						 * I don’t know why this is */
-						opt: Ok((opt as u8 as char).to_string()),
-					})
-				},
-            };
-
-			/* delloc argv (something online said I should do this) */
-			let _ = Box::from_raw(boxed);
-			return ret;
-        }
-    }
-}
-
-/* tests (good) */
-#[cfg(test)]
-mod tests {
-	use GetOpt;
-
-	#[test]
-	fn testing() {
-		let argv: Vec<String> = ["test", "-b", "-f", "arg", "-o", "arg"]
-			.iter()
-			.map(|s| s.to_string())
-			.collect();
-
-		while let Some(opt) = argv.getopt(":abf:o:") {
-			match opt.opt() {
-				Ok("a") => assert_eq!(opt.ind(), 1),
-				Ok("b") => assert_eq!(opt.ind(), 2),
-				Ok("f") | Ok("o") => {
-					assert_eq!(opt.arg(), Some("arg".into()));
-				},
-				_ => assert!(false),
-			};
-		}
-
-		if let Some(opt) = argv.getopt("abc:") {
-			opt.clone().set_ind(1);
-			assert_eq!(opt.ind(), 1);
-		}
-	}
-}

src/libstrerror.rs

@@ -1,31 +0,0 @@
-/*
- * Copyright (c) 2024 Emma Tebibyte <emma@tebibyte.media>
- * SPDX-License-Identifier: FSFAP
- *
- * 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 any warranty.
- */
-
-use std::ffi::{ c_int, c_char, CStr };
-
-pub trait StrError { fn strerror(&self) -> String; }
-
-impl StrError for std::io::Error {
-	/* wrapper function for use in Rust */
-	fn strerror(&self) -> String {
-		/* Get the raw OS error. If it’s None, what the hell is going on‽ */
-		let errno = self.raw_os_error().unwrap_or(0) as c_int;
-
-		/* Get a CStr from the error message so that it’s referenced and then
-		 * convert it to an owned value. If the string is not valid UTF-8,
-		 * return that error instead. */
-		match unsafe { CStr::from_ptr(strerror(errno)) }.to_str() {
-			Ok(s) => s.to_owned(), // yay!! :D
-			Err(e) => e.to_string(), // awww :(
-		}
-	}
-}
-
-/* binding to strerror(3p) */
-extern "C" { fn strerror(errnum: c_int) -> *mut c_char; }

src/mm.c

@@ -1,236 +0,0 @@
-/*
- * Copyright (c) 2024 DTB <trinity@trinity.moe>
- * SPDX-License-Identifier: AGPL-3.0-or-later
- *
- * This program is free software: you can redistribute it and/or modify it under
- * the terms of the GNU Affero General Public License as published by the Free
- * Software Foundation, either version 3 of the License, or (at your option) any
- * later version.
- *
- * This program is distributed in the hope that it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
- * FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
- * details.
- *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program. If not, see https://www.gnu.org/licenses/.
- */
-
-#include <errno.h> /* errno */
-#include <signal.h> /* signal(2), SIG_ERR, SIG_IGN, SIGINT */
-#include <stdio.h> /* fclose(3), fopen(3), fprintf(3), getc(3), putc(3),
-                    * setvbuf(3), size_t, _IONBF, NULL */
-#include <stdlib.h> /* free(3), realloc(3) */
-#include <string.h> /* strcmp(3), strerror(3) */
-#include <unistd.h> /* getopt(3) */
-#if !defined EX_IOERR || !defined EX_OK || !defined EX_OSERR \
-		|| !defined EX_USAGE
-#	include <sysexits.h>
-#endif
-extern int errno;
-
-/* This structure is how open files are tracked. */
-struct Files{
-	size_t a;	/* allocation */
-	size_t s;	/* used size */
-	char *mode;	/* file opening mode */
-	char **names;	/* file names */
-	FILE **files;	/* file pointers */
-};
-
-/* How much to grow the allocation when it's saturated. */
-#ifndef ALLOC_INCREMENT
-#	define ALLOC_INCREMENT 1
-#endif
-
-/* How much to grow the allocation at program start. */
-#ifndef ALLOC_INITIAL
-#	define ALLOC_INITIAL 10
-#endif
-
-/* pre-allocated strings */
-static char *program_name = "<no argv[0]>";
-static char *stdin_name = "<stdin>";
-static char *stdout_name = "<stdout>";
-static char *stderr_name = "<stderr>";
-static char *(fmode[]) = { (char []){"rb"}, (char []){"rb+"} };
-static char *wharsh = "wb";
-
-/* Adds the open FILE pointer for the file at the path s to the files struct,
- * returning the FILE if successful and NULL if not, allocating more memory in
- * the files buffers as needed. */
-static FILE *
-Files_append(struct Files *files, FILE *file, char *name){
-
-	if(file == NULL || (files->s == files->a
-			&& ((files->files = realloc(files->files,
-					(files->a += (files->a == 0)
-						? ALLOC_INITIAL
-						: ALLOC_INCREMENT)
-					* sizeof *(files->files))) == NULL
-				|| (files->names = realloc(files->names,
-					files->a * sizeof *(files->names))) == NULL)))
-		return NULL;
-
-	files->names[files->s] = name;
-	return files->files[files->s++] = file;
-}
-
-/* Opens the file at the path p and puts it in the files struct, returning NULL
- * if either the opening or the placement of the open FILE pointer fail. */
-#define Files_open(files, p) \
-	Files_append((files), fopen((p), (files)->mode), (p))
-
-/* Prints a diagnostic message based on errno and returns an exit status
- * appropriate for an OS error. */
-static int
-oserr(char *s, char *r){
-
-	fprintf(stderr, "%s: %s: %s\n", s, r, strerror(errno));
-
-	return EX_OSERR;
-}
-
-/* Hijacks i and j from main and destructs the files[2] struct used by main by
- * closing its files and freeing its files and names arrays, returning retval
- * from main. */
-#define terminate \
-	for(i = 0; i < 2; ++i){ \
-		for(j = 0; j < files[i].s; ++j) \
-			if(files[i].files[j] != stdin \
-					&& files[i].files[j] != stdout \
-					&& files[i].files[j] != stderr) \
-				fclose(files[i].files[j]); \
-		free(files[i].files); \
-		free(files[i].names); \
-	} \
-	return retval
-
-/* Prints a usage text, in which s is the program being run (i.e. argv[0]), and
- * returns an exit status appropriate for a usage error. */
-int usage(char *s){
-
-	fprintf(stderr, "Usage: %s [-aenu] [-i input]... [-o output]...\n", s);
-
-	return EX_USAGE;
-}
-
-int main(int argc, char *argv[]){
-	int c;
-	struct Files files[2]; /* {read, write} */
-	size_t i;
-	size_t j;
-	size_t k; /* loop index but also unbuffer status */
-	int retval;
-
-	/* Initializes the files structs with their default values, standard
-	 * input and standard output. If an input or an output is specified
-	 * these initial values will be overwritten, so to, say, use mm(1)
-	 * equivalently to tee(1p), -o - will need to be specified before
-	 * additional files to ensure standard output is still written. */
-	for(i = 0; i < 2; ++i){
-		files[i].a = 0;
-		files[i].s = 0;
-		files[i].mode = fmode[i];
-		files[i].files = NULL;
-		files[i].names = NULL;
-		Files_append(&files[i], i == 0 ? stdin : stdout,
-			i == 0 ? stdin_name : stdout_name);
-		files[i].s = 0;
-	}
-
-	k = 0;
-
-	if(argc > 0)
-		program_name = argv[0];
-
-	if(argc > 1)
-		while((c = getopt(argc, argv, "aehi:no:u")) != -1)
-			switch(c){
-			case 'a': /* "rb+" -> "ab" */
-				files[1].mode[0] = 'a';
-				files[1].mode[2] = '\0';
-				break;
-			case 'e':
-				if(Files_append(&files[1], stderr, stderr_name) != NULL)
-					break;
-				retval = oserr(argv[0], "-e");
-				terminate;
-			case 'i':
-				if((strcmp(optarg, "-") == 0 && Files_append(&files[0],
-							stdin, stdin_name) != NULL)
-						|| Files_open(&files[0], optarg) != NULL)
-					break;
-				retval = oserr(argv[0], optarg);
-				terminate;
-			case 'o':
-				if((strcmp(optarg, "-") == 0 && Files_append(&files[1],
-							stdout, stdout_name) != NULL)
-						|| Files_open(&files[1], optarg) != NULL)
-					break;
-				/* does not exist, so try to create it */
-				if(errno == ENOENT){
-					files[1].mode = wharsh;
-					if(Files_open(&files[1], optarg) != NULL){
-						files[1].mode = fmode[1];
-						break;
-					}
-				}
-				retval = oserr(argv[0], optarg);
-				terminate;
-			case 'n':
-				if(signal(SIGINT, SIG_IGN) != SIG_ERR)
-					break;
-				retval = oserr(argv[0], "-n");
-				terminate;
-			case 'u':
-				k = 1;
-				break;
-			default:
-				retval = usage(argv[0]);
-				terminate;
-			}
-
-	if(optind != argc){
-		retval = usage(argv[0]);
-		terminate;
-	}
-
-	files[0].s += files[0].s == 0;
-	files[1].s += files[1].s == 0;
-	
-	/* Unbuffer files. */
-	if(k){
-		for(i = 0;
-			i < files[0].s;
-			setvbuf(files[0].files[i++], NULL, _IONBF, 0));
-		for(i = 0;
-			i < files[1].s;
-			setvbuf(files[1].files[i++], NULL, _IONBF, 0));
-	}
-
-	retval = EX_OK;
-
-	/* Actual program loop. */
-	for(i = 0; i < files[0].s; ++i) /* iterate ins */
-		while((c = getc(files[0].files[i])) != EOF) /* iterate chars */
-			for(j = 0; j < files[1].s; ++j) /* iterate outs */
-				if(putc(c, files[1].files[j]) == EOF){
-					/* notebook's full */
-					retval = EX_IOERR;
-					fprintf(stderr, "%s: %s: %s\n",
-						program_name, files[1].names[j], strerror(errno));
-					if(fclose(files[1].files[j]) == EOF)
-						fprintf(stderr, "%s: %s: %s\n",
-							program_name, files[1].names[j], strerror(errno));
-					/* massage out the tense muscle */
-					for(k = j--; k < files[1].s - 1; ++k){
-						files[1].files[k] = files[1].files[k+1];
-						files[1].names[k] = files[1].names[k+1];
-					}
-					if(--files[1].s == 0)
-						terminate;
-				}
-
-	terminate;
-}

src/npc.c

@@ -39,7 +39,7 @@ int main(int argc, char *argv[]){
 			}
 
 	if(argc > optind){
-usage:		fprintf(stderr, "Usage: %s [-et]\n", argv[0]);
+usage:		fprintf(stderr, "Usage: %s (-eht)\n", argv[0]);
 		return EX_USAGE;
 	}
 

src/rpn.rs

@@ -172,7 +172,7 @@ fn eval(
 					};
 				} else {
 					return Err(EvaluationError {
-						message: format!("{}: Unexpected operation", op),
+						message: format!("{}: Unexpected operation.", op),
 						code: EX_DATAERR,
 					})
 				}

src/scrut.c

@@ -1,6 +1,5 @@
 /*
- * Copyright (c) 2023–2024 DTB <trinity@trinity.moe>
+ * Copyright (c) 2023 DTB <trinity@trinity.moe>
- * Copyright (c) 2024 Emma Tebibyte <emma@tebibyte.media>
  * SPDX-License-Identifier: AGPL-3.0-or-later
  *
  * This program is free software: you can redistribute it and/or modify it under
@@ -18,15 +17,13 @@
  */
 
 #include <stdio.h> /* fprintf(3), stderr, NULL */
-#include <stdlib.h> /* EXIT_FAILURE, EXIT_SUCCESS */
+#include <stdlib.h> /* EXIT_FAILURE */
 #include <string.h> /* memset(3), strchr(3) */
-#ifndef EX_USAGE
-#	include <sysexits.h>
-#endif
 #include <unistd.h> /* access(3), getopt(3), F_OK, R_OK, W_OK, X_OK */
 #include <sys/stat.h> /* lstat(3), stat struct, S_ISBLK, S_ISCHR, S_ISDIR,
                        * S_ISFIFO, S_ISGID, S_ISREG, S_ISLNK, S_ISSOCK,
                        * S_ISUID, S_ISVTX */
+#include <sysexits.h>
 
 static char args[] = "bcdefghkprsuwxLS";
 static char ops[(sizeof args) / (sizeof *args)];
@@ -60,13 +57,13 @@ int main(int argc, char *argv[]){
 
 	argv += optind;
 	do{	if(access(*argv, F_OK) != 0 || lstat(*argv, &buf) == -1)
-			return EXIT_FAILURE; /* doesn't exist or isn't stattable */
+			return 1; /* doesn't exist or isn't stattable */
 
 		for(i = 0; ops[i] != '\0'; ++i)
 			if(ops[i] == 'e')
 				continue;
 			else if(ops[i] == 'h'){
-usage:				fprintf(stderr, "Usage: %s [-%s] file...\n",
+usage:				fprintf(stderr, "Usage: %s (-%s) [file...]\n",
 					argv[0] == NULL
 						? program_name
 						: argv[0],
@@ -100,8 +97,8 @@ usage:				fprintf(stderr, "Usage: %s [-%s] file...\n",
 						&& !S_ISLNK(buf.st_mode))
 					|| (ops[i] == 'S'
 						&& !S_ISSOCK(buf.st_mode)))
-				return EXIT_FAILURE;
+				return 1;
 	}while(*++argv != NULL);
 
-	return EXIT_SUCCESS;
+	return 0;
 }

src/str.c

@@ -56,7 +56,7 @@ int main(int argc, char *argv[]){
 				goto pass;
 	}
 
-	fprintf(stderr, "Usage: %s type string...\n",
+	fprintf(stderr, "Usage: %s [type] [string...]\n",
 		argv[0] == NULL ? program_name : argv[0]);
 
 	return EX_USAGE;

src/strcmp.c

@@ -8,7 +8,7 @@ int main(int argc, char *argv[]){
 	int i;
 
 	if(argc < 3){
-		fprintf(stderr, "Usage: %s string string...\n",
+		fprintf(stderr, "Usage: %s [string] [string...]\n",
 			argv[0] == NULL ? program_name : argv[0]);
 		return EX_USAGE;
 	}

src/swab.rs

@@ -1,87 +0,0 @@
-/*
- * Copyright (c) 2024 DTB <trinity@trinity.moe>
- * SPDX-License-Identifier: AGPL-3.0-or-later
- *
- * This program is free software: you can redistribute it and/or modify it under
- * the terms of the GNU Affero General Public License as published by the Free
- * Software Foundation, either version 3 of the License, or (at your option) any
- * later version.
- * 
- * This program is distributed in the hope that it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
- * FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
- * details.
- *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program. If not, see https://www.gnu.org/licenses/.
- */
-
-use std::{
-	env::args,
-	io::{ stdin, stdout, Error, ErrorKind, Read, Write },
-	process::ExitCode,
-	vec::Vec
-};
-
-extern crate getopt;
-use getopt::GetOpt;
-
-extern crate sysexits;
-use sysexits::{ EX_OK, EX_OSERR, EX_USAGE };
-
-fn oserr(s: &str, e: Error) -> ExitCode {
-	eprintln!("{}: {}", s, e);
-	ExitCode::from(EX_OSERR as u8)
-}
-
-fn usage(s: &str) -> ExitCode {
-	eprintln!("Usage: {} [-f] [-w word_size]", s);
-	ExitCode::from(EX_USAGE as u8)
-}
-
-fn main() -> ExitCode {
-	let argv = args().collect::<Vec<String>>();
-	let mut buf: Vec<u8> = Vec::new();
-	let mut input = stdin();
-	let mut output = stdout().lock();
-
-	let mut force = false;
-	let mut wordsize: usize = 2;
-
-	while let Some(opt) = argv.getopt("fw:") {
-		match opt.opt() {
-			Ok("f") => force = true,
-			Ok("w") => {
-				if let Some(arg) = opt.arg() {
-					match arg.parse::<usize>() {
-						Ok(w) if w % 2 == 0 => { wordsize = w; () },
-						_ => { return usage(&argv[0]); },
-					}
-				}
-			},
-			_ => { return usage(&argv[0]); }
-		}
-	}
-
-	buf.resize(wordsize, 0);
-
-	loop {
-		match input.read(&mut buf) {
-			Ok(0) => break ExitCode::from(EX_OK as u8),
-			Ok(v) if v == wordsize => {
-				let (left, right) = buf.split_at(v/2);
-				if let Err(e) = output.write(&right)
-						.and_then(|_| output.write(&left)) {
-					break oserr(&argv[0], e)
-				}
-			},
-			Ok(v) => {
-				if let Err(e) = output.write(&buf[..v]) {
-					break oserr(&argv[0], e)
-				}
-			},
-			Err(e) if e.kind() == ErrorKind::Interrupted && force => continue,
-			Err(e) => break oserr(&argv[0], e)
-		}
-	}
-}