Merge branch 'swab' (closes #22)

.editorconfig

@@ -12,6 +12,3 @@ indent_size = 2
 
 [*.sh]
 indent_size = 2
-
-[configure]
-indent_size = 2

CONTRIBUTING

@@ -90,26 +90,44 @@ notice:
  *     USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-When writing code, make sure lines never exceed 80 characters in width when
-using four-character-wide indentation steps.
+Make sure lines never exceed 80 columns in width when using four-character
+indentation steps. This helps contributors with smaller screens, those using
+side-by-side editor windows or panes, and those who have no text wrapping in
+their editor or terminal.
 
-For usage text and help messages, please do not implement a -h option. Just
-print usage information when any erroneous option is specified. Follow the
-NetBSD style guide for usage text output format [1].
+For usage text and help messages, do not implement a -h option. Instead, print
+usage information when any erroneous option is specified. Follow the NetBSD
+style guide for the usage text’s output format [1].
 
-If committing a new source file for a utility, format the commit message like
-this:
+[1] <http://cvsweb.netbsd.org/bsdweb.cgi/~checkout~/src/share/misc/style>
 
-$ git commit -m 'tool(1): <information>'
+If committing a new source file, format the commit message following these
+guidelines:
+
+$ git commit -m 'tool(1): add feature x'
 
 If committing a new library or header file:
 
-$ git commit -m 'library(1): <information>'
+$ git commit -m 'library(3): fix overflow'
+$ git commit -m 'header.h(3): add header.h(3)'
+
+If committing a new manual page:
+
+$ git commit -m 'tool.1: add author details'
 
 If modifying some other file or directory:
 
-$ git commit -m 'README: clarification'
-$ git commit -m 'tests: posix: fixed bug #47'
-$ git commit -m 'docs: tool(1): added author information'
+$ git commit -m 'README: clarify'
+$ git commit -m 'tests/posix: fix bug #47'
 
-etc.
+For multiple of these:
+
+$ git commit -m 'Makefile, tool(1): add tool(1)'
+$ git commit -m 'tool(1): add tool(1); library(3), library.3: add library(3)'
+$ git commit -m 'tool(1): fix #42 & add feature x'
+
+Commit messages should be written in the present tense.
+
+--
+This work © 2023–2024 by Emma Tebibyte is licensed under CC BY-SA 4.0. To view a
+copy of this license, visit <http://creativecommons.org/licenses/by-sa/4.0/>

Makefile

@@ -17,7 +17,7 @@ CC=cc
 RUSTC=rustc
 
 .PHONY: all
-all: dj false fop intcmp rpn scrut str strcmp true
+all: dj false fop hru intcmp rpn scrut str strcmp swab true
 
 build:
 	# keep build/include until bindgen(1) has stdin support
@@ -54,7 +54,7 @@ build/o/libsysexits.rlib: build
 		| $(RUSTC) $(RUSTFLAGS) --crate-type lib -o build/o/libsysexits.rlib -
 
 build/o/libgetopt.rlib: src/getopt-rs/lib.rs
-	$(RUSTC) $(RUSTCFLAGS) --crate-type=lib --crate-name=getopt \
+	$(RUSTC) $(RUSTFLAGS) --crate-type=lib --crate-name=getopt \
 		-o build/o/libgetopt.rlib src/getopt-rs/lib.rs
 
 .PHONY: dj
@@ -74,6 +74,13 @@ build/bin/fop: src/fop.rs build build/o/libgetopt.rlib build/o/libsysexits.rlib
 		--extern sysexits=build/o/libsysexits.rlib \
 		-o $@ src/fop.rs
 
+.PHONY: hru
+hru: build/bin/hru
+build/bin/hru: src/hru.rs build build/o/libgetopt.rlib build/o/libsysexits.rlib
+	$(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
@@ -101,6 +108,13 @@ 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 build/o/libsysexits.rlib
+	$(RUSTC) $(RUSTFLAGS) --extern getopt=build/o/libgetopt.rlib \
+		--extern sysexits=build/o/libsysexits.rlib \
+		-o $@ src/swab.rs
+
 .PHONY: true
 true: build/bin/true
 build/bin/true: src/true.c build

README

@@ -17,6 +17,31 @@ purposes beyond its scope.
 
 See docs/ for more on the specific utilities currently implemented.
 
+Building
+
+The coreutils require a POSIX-compliant environment to compile, including a C
+compiler and preprocessor (cc(1) and cpp(1) by default) with the -idirafter
+flag, a Rust compiler (rustc(1) by default), bindgen(1), and a POSIX-compliant
+make(1) utility.
+
+To build and install:
+
+$ make
+$ make PREFIX="/your/preferred/location" install
+
+To build with a different compiler than the default:
+
+$ make CC=clang
+$ make RUSTC=gccrs
+
+To test the utilities:
+
+$ make test
+
+To remove all untracked files:
+
+$ make clean
+
 Read More
 
 An Introduction to the Unix Shell
@@ -30,3 +55,10 @@ Master Foo Discourses on the Unix-Nature
 
 Shell Programming!
 <https://tldp.org/LDP/abs/html/why-shell.html>
+
+--
+Copyright © 2023–2024 Emma Tebibyte <emma@tebibyte.media>
+Copyright © 2024 DTB <trinity@trinity.moe>
+
+This work is licensed under CC BY-SA 4.0. To view a copy of this license, visit
+<http://creativecommons.org/licenses/by-sa/4.0/>.

docs/hru.1

@@ -0,0 +1,57 @@
+.\" 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 rpn 1
+
+.SH NAME
+
+hru \(en human readable units
+
+.SH SYNOPSIS
+
+hru
+
+.SH DESCRIPTION
+
+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
+defined by the International System of Units.
+
+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, hru will exit with
+the appropriate error code as defined by sysexits.h(3) and print an error
+message.
+
+.SH RATIONALE
+
+The GNU project’s ls(1) implementation contains a human-readable option (-h)
+that, when specified, makes the tool print size information in a format more
+immediately readable. This functionality is useful not only in the context of
+ls(1) so the decision was made to split it into a new tool. The original
+functionality in GNU’s ls(1) can be emulated with fop(1) combined with this
+program.
+
+.SH STANDARDS
+
+Hru follows the standard unit prefixes as specified by the Bureau International
+des Poids et Mesures (BIPM) in the ninth edition of The International System of
+Units (SI).
+
+.SH AUTHOR
+
+Written by Emma Tebibyte <emma@tebibyte.media>.
+
+.SH COPYRIGHT
+
+Copyright (c) 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later
+<https://gnu.org/licenses/agpl.html>.
+
+.SH SEE ALSO
+
+GNU ls(1), The International System of Units (SI) 9th Edition

docs/scrut.1

@@ -0,0 +1,93 @@
+.\" 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 scrut 1
+
+.SH NAME
+
+scrut \(en scrutinize file properties
+
+.SH SYNOPSIS
+
+scrut
+.RB ( -bcdefgkprsuwxLS )
+.RB [ file... ]
+
+.SH DESCRIPTION
+
+Scrut determines if given files comply with the opted requirements.
+
+.SH OPTIONS
+
+.B -b
+requires the given files to exist and be block special files.
+.PP
+.B -c
+requires the given files to exist and be character special files.
+.PP
+.B -d
+requires the given files to exist and be directories.
+.PP
+.B -e
+requires the given files to exist, and is redundant to any other option.
+.PP
+.B -e
+requires the given files to exist and be regular files.
+.PP
+.B -g
+requires the given files to exist and have their set group ID flags set.
+.PP
+.B -k
+requires the given files to exist and have their sticky bit set.
+.PP
+.B -p
+requires the given files to exist and be named pipes.
+.PP
+.B -r
+requires the given files to exist and be readable.
+.PP
+.B -u
+requires the given files to exist and have their set user ID flags set.
+.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.
+
+.SH EXIT STATUS
+
+Scrut prints a debug message and exits unsuccessfully with the appropriate
+sysexits.h(3) error code if invoked incorrectly. Scrut exits successfully if
+the given files comply with their requirements and unsuccessfully otherwise.
+
+.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 <trinity@trinity.moe>.
+
+.SH COPYRIGHT
+
+Copyright © 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
+<https://gnu.org/licenses/agpl.html>.
+
+.SH SEE ALSO
+
+access(3p), lstat(3p), test(1p)

docs/swab.1

@@ -0,0 +1,71 @@
+.\" 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 swab 1
+
+.SH NAME
+
+swab \(en swap bytes
+
+.SH SYNOPSIS
+
+swab
+.RB ( -f )
+.RB ( -w
+.R [
+.B word size
+.R ])
+
+.SH USAGE
+
+Swab swaps the latter and former halves of a block of bytes.
+
+.SH EXAMPLES
+
+The following sh(1p) line:
+
+.R printf 'hello world!\n' | swab
+
+Produces the following output:
+
+.R ehll oowlr!d
+
+.SH OPTIONS
+
+The
+.B -f
+option ignores system call interruptions.
+.PP
+The
+.B -w
+option configures the word size; that is, the size in bytes of the block size
+on which to operate. By default the word size is 2. The word size must be
+cleanly divisible by 2, otherwise the block of bytes being processed can't be
+halved.
+
+.SH DIAGNOSTICS
+
+If an error is encountered in input, output, or invocation, a diagnostic
+message will be written to standard error and swab will exit with the
+appropriate status from sysexits.h(3).
+
+.SH RATIONALE
+
+Swab was modeled after the
+.R conv=swab
+functionality specified in the POSIX dd utility but additionally allows the
+word size to be configured.
+.PP
+Swab is useful for fixing the endianness of binary files produced on other
+machines.
+
+.SH COPYRIGHT
+
+Copyright (c) 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
+<https://gnu.org/licenses/agpl.html>.
+
+.SH SEE ALSO
+
+dd(1p)

src/fop.rs

@@ -18,7 +18,7 @@
 
 use std::{
 	env::args,
-	io::{ Read, stdin, Write },
+	io::{ Read, stdin, stdout, Write },
 	process::{ Command, exit, Stdio },
 };
 
@@ -26,7 +26,7 @@ extern crate sysexits;
 extern crate getopt;
 
 use getopt::{ Opt, Parser };
-use sysexits::{ EX_DATAERR, EX_USAGE };
+use sysexits::{ EX_DATAERR, EX_IOERR, EX_UNAVAILABLE, EX_USAGE };
 
 fn main() {
 	let argv = args().collect::<Vec<String>>();
@@ -54,43 +54,65 @@ fn main() {
 		exit(EX_USAGE);
 	});
 
-	let index = argv[index_arg].parse::<usize>().unwrap_or_else(|_| {
-		eprintln!("{}: {}: Not an integer.", argv[0], argv[1]);
+	let index = argv[index_arg].parse::<usize>().unwrap_or_else(|e| {
+		eprintln!("{}: {}: {}.", argv[0], argv[1], e);
 		exit(EX_DATAERR);
 	});
 
 	let mut buf = String::new();
-	stdin().read_to_string(&mut buf).unwrap();
+	let _ = stdin().read_to_string(&mut buf);
 	let mut fields = buf.split(d).collect::<Vec<&str>>();
 
-	let opts = argv.iter().clone().skip(command_arg + 1).collect::<Vec<&String>>();
+	let opts = argv
+		.iter()
+		.clone()
+		.skip(command_arg + 1)
+		.collect::<Vec<&String>>();
 
 	let mut spawned = Command::new(argv.get(command_arg).unwrap())
 		.args(opts)
 		.stdin(Stdio::piped())
 		.stdout(Stdio::piped())
 		.spawn()
-		.unwrap();
+		.unwrap_or_else( |e| {
+			eprintln!("{}: {}: {}.", argv[0], argv[command_arg], e);
+			exit(EX_UNAVAILABLE);
+		});
 
 	let field = fields.get(index).unwrap_or_else(|| {
 		eprintln!(
 			"{}: {}: No such index in input.",
 			argv[0],
-			index.to_string()
+			index.to_string(),
 		);
 		exit(EX_DATAERR);
 	});
 
 	if let Some(mut child_stdin) = spawned.stdin.take() {
-		child_stdin.write_all(field.as_bytes()).unwrap();
+		let _ = child_stdin.write_all(field.as_bytes());
 		drop(child_stdin);
 	}
 
-	let output = spawned.wait_with_output().unwrap();
+	let output = spawned.wait_with_output().unwrap_or_else(|e| {
+		eprintln!("{}: {}: {}.", argv[0], argv[command_arg], e);
+		exit(EX_IOERR);
+	});
 
-	let new_field = String::from_utf8(output.stdout).unwrap();
+	let mut replace = output.stdout.clone();
+
+	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);
+		exit(EX_IOERR);
+	});
 
 	fields[index] = &new_field;
 
-	print!("{}", fields.join(&d.to_string()));
+	stdout().write_all(
+		fields.join(&d.to_string()).as_bytes()
+	).unwrap_or_else(|e|{
+		eprintln!("{}: {}.", argv[0], e);
+		exit(EX_IOERR);
+	});
 }

src/hru.rs

@@ -0,0 +1,107 @@
+/*
+ * 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::{
+	cmp::Ordering,
+	env::args,
+	io::{ stdin, stdout, Write },
+	process::{ ExitCode, exit },
+};
+
+extern crate sysexits;
+
+use sysexits::{ EX_DATAERR, EX_IOERR, EX_SOFTWARE };
+
+const LIST: [(u32, &str); 10] = [
+	(3, "k"),
+	(6, "M"),
+	(9, "G"),
+	(12, "T"),
+	(15, "P"),
+	(18, "E"),
+	(21, "Z"),
+	(24, "Y"),
+	(27, "R"),
+	(30, "Q")
+];
+
+fn convert(input: u128) -> Result<(f64, (u32, &'static str)), String> {
+
+	let mut out = (input as f64, (0_u32, ""));
+	if input < 1000 { return Ok(out); }
+
+	for (n, p) in LIST {
+		let c = match 10_u128.checked_pow(n) {
+			Some(c) => c,
+			None => {
+				return Err(format!("10^{}: Integer overflow.", n.to_string()));
+			},
+		};
+
+		match c.cmp(&input) {
+			Ordering::Less => {
+				out = (input as f64 / c as f64, (n, p));
+			},
+			Ordering::Equal => {
+				return Ok((input as f64 / c as f64, (n, p)));
+			},
+			Ordering::Greater => {},
+		};
+	}
+
+	Ok(out)
+}
+
+fn main() -> ExitCode {
+	let argv = args().collect::<Vec<String>>();
+	let mut buf = String::new();
+	while let Ok(_) = stdin().read_line(&mut buf) {
+		if buf.is_empty() { return ExitCode::SUCCESS; }
+
+		let n: u128 = match buf.trim().parse() {
+			Ok(f) => {
+				buf.clear();
+				f
+			},
+			Err(err) => {
+				eprintln!("{}: {}.", argv[0], err);
+				return ExitCode::from(EX_DATAERR as u8);
+			},
+		};
+
+		let (number, prefix) = match convert(n) {
+			Ok(x) => x,
+			Err(err) => {
+				eprintln!("{}: {}.", argv[0], err);
+				return ExitCode::from(EX_SOFTWARE as u8);
+			},
+		};
+
+		let si_prefix = format!("{}B", prefix.1);
+
+		let out = ((number * 10.0).round() / 10.0).to_string();
+
+		stdout().write_all(format!("{} {}\n", out, si_prefix).as_bytes())
+			.unwrap_or_else(|e| {
+				eprintln!("{}: {}.", argv[0], e);
+				exit(EX_IOERR);
+			});
+	}
+
+	ExitCode::SUCCESS
+}

src/scrut.c

@@ -18,7 +18,7 @@
 
 #include <stdio.h> /* fprintf(3), stderr, NULL */
 #include <stdlib.h> /* EXIT_FAILURE */
-#include <string.h> /* strchr(3) */
+#include <string.h> /* memset(3), strchr(3) */
 #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,
@@ -33,17 +33,24 @@ int main(int argc, char *argv[]){
 	struct stat buf;
 	int c;
 	size_t i;
+	char *p;
 
 	if(argc < 2)
 		goto usage;
 
-	i = 0;
+	memset(ops, '\0', sizeof ops);
 	while((c = getopt(argc, argv, args)) != -1)
-		if(strchr(args, c) == NULL)
+		if((p = strchr(args, c)) == NULL)
 			goto usage;
 		else
-			ops[i++] = c;
-	ops[i] = '\0';
+			ops[p - args] = c;
+	/* straighten out ops */
+	for(i = 0, p = ops; i < (sizeof ops) / (sizeof *ops); ++i)
+		if(ops[i] != '\0'){
+			*p = ops[i];
+			if(&ops[i] != p++)
+				ops[i] = '\0';
+		}
 
 	if(optind == argc)
 		goto usage;

src/swab.rs

@@ -0,0 +1,90 @@
+/*
+ * 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::{ Opt, Parser };
+
+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 [wordsize])", 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 opts = Parser::new(&argv, "fw:");
+	let mut force = false;
+	let mut wordsize: usize = 2;
+
+	loop {
+		match opts.next() {
+			None => break,
+			Some(opt) =>
+				match opt {
+					Ok(Opt('f', None)) => force = true,
+					Ok(Opt('w', Some(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)
+		}
+	}
+}