bonsai/harakit
4
4
Fork 3
Code Issues 41 Pull Requests 2 Projects 1 Releases 35 Activity

Merge branch 'main' into getopt-bindings

Browse Source
This commit is contained in:
Emma Tebibyte 2024-06-23 00:57:20 -06:00
commit 965d1bb76e
Signed by: emma
GPG Key ID: 06FA419A1698C270
21 changed files with 824 additions and 562 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

83
CONDUCT Normal file
View File

@ -0,0 +1,83 @@
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>

2
CONTRIBUTING
View File

@ -1,3 +1,5 @@
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

20
Makefile
View File

@ -8,15 +8,16 @@
# permitted in any medium without royalty provided the copyright notice and this
# notice are preserved. This file is offered as-is, without any warranty.
.POSIX:
# The octal escape \043 is utilized twice in this file as make(1p) will
# interpret a hash in a rule as an inline comment.
# if using BSD make(1), remove these pragmas because they break it
.PRAGMA: posix_202x # future POSIX standard support à la pdpmake(1)
.PRAGMA: command_comment # breaks without this?
.POSIX:
DESTDIR ?= dist
PREFIX ?= /usr/local
MANDIR != [ $(PREFIX) = / ] && printf '/usr/share/man\n' \
|| printf '/share/man\n'
SYSEXITS != printf '\043include <sysexits.h>\n' | cpp -M - | sed 's/ /\n/g' \
| sed -n 's/sysexits\.h//p' || printf 'include\n'
@ -30,9 +31,9 @@ CFLAGS += -I$(SYSEXITS)
.PHONY: all
all: dj false fop hru intcmp mm npc rpn scrut str strcmp swab true
# keep build/include until bindgen(1) has stdin support
# https://github.com/rust-lang/rust-bindgen/issues/2703
build:
# 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
@ -42,7 +43,7 @@ clean:
dist: all
mkdir -p $(DESTDIR)/$(PREFIX)/bin $(DESTDIR)/$(PREFIX)/share/man/man1
cp build/bin/* $(DESTDIR)/$(PREFIX)/bin
cp docs/*.1 $(DESTDIR)/$(PREFIX)/share/man/man1
cp docs/*.1 $(DESTDIR)/$(PREFIX)/$(MANDIR)/man1
.PHONY: install
install: dist
@ -68,9 +69,9 @@ build/o/libstrerror.rlib: build src/strerror.rs
$(RUSTC) $(RUSTFLAGS) --crate-type=lib -o $@ \
src/strerror.rs
# bandage solution until bindgen(1) gets stdin support
build/o/libsysexits.rlib: build $(SYSEXITS)sysexits.h
# bandage solution until bindgen(1) gets stdin support
printf '#define EXIT_FAILURE 1\n' | cat - $(SYSEXITS)sysexits.h \
printf '\043define EXIT_FAILURE 1\n' | cat - $(SYSEXITS)sysexits.h \
> build/include/sysexits.h
bindgen --default-macro-constant-type signed --use-core --formatter=none \
build/include/sysexits.h | $(RUSTC) $(RUSTFLAGS) --crate-type lib -o $@ -
@ -105,7 +106,6 @@ 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

16
README
View File

@ -1,9 +1,11 @@
“Seek not to walk the path of the masters; seek what they sought.”
– Matsuo Basho
The Bonsai core utilities are the result of the careful examination of the
current state of POSIX and Unix utilies. The Unix Philosophy, “do one thing and
do it well” is its core but these tools do not cling to the names of the past.
The Bonsai core utilities are a replacement for standard POSIX utilities which
aim to fill its niche while expanding on their capabilities. These new tools are
the result of the careful examination of the current state of POSIX 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. The new, non-POSIX era of this project started with frustration
@ -20,9 +22,9 @@ 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.
compiler and preprocessor (cc(1) and cpp(1) by default), an edition 2023 Rust
compiler (rustc(1) by default), bindgen(1), and a POSIX-compliant make(1)
utility.
To build and install:
@ -38,7 +40,7 @@ To test the utilities:
$ make test
To remove all untracked files:
To remove all build and distributable files:
$ make clean

255
docs/dj.1
View File

@ -1,14 +1,13 @@
.\" 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
.\"
.TH DJ 1 2024-06-17 "Bonsai Core Utilites 0.13.11"
.SH NAME
dj \(en disk jockey
.\"
.SH SYNOPSIS
dj
@ -19,142 +18,172 @@ dj
.RB [ count ])
.RB ( -i
.R [
.B input file
.R ])
[\fBinput file\fP])
.RB ( -b
.R [
.B input block size
.R ])
[\fBinput block size\fP])
.RB ( -s
.R [
.B input offset
.R ])
[\fBinput offset\fP])
.RB ( -o
.R [
.B output file
.R ])
[\fBoutput file\fP])
.RB ( -B
.R [
.B output block size
.R ])
[\fBoutput block size\fP])
.RB ( -S
.R [
.B output offset
.R ])
[\fBoutput offset\fP])
.\"
.SH DESCRIPTION
.SH USAGE
Perform precise read and write operations on files. This utility is useful for
reading and writing binary data to and from disks.
The
.B -i
option takes a path as an argument to open and use in place of standard input.
The
.B -o
option does the same in place of standard output. Dj does not truncate output
files and instead writes over the bytes in the existing file.
.PP
The
This manual page uses the terms \(lqskip\(rq and \(lqseek\(rq to refer to moving
to a specified byte by index in the input and output of the program
respectively. This language is inherited from the
.BR dd (1p)
utility and used here to decrease ambiguity.
When seeking or skipping to a byte, writing or reading starts at the byte
immediately subsequent to the specified byte.
.\"
.SH OPTIONS
.IP \fB-i\fP
Takes a file path as an argument and opens it for use as an input.
.IP \fB-b\fP
Takes a numeric argument as the size in bytes of the input buffer, the default
being 1024.
.IP \fB-s\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
Takes a file path as an argument and opens it for use as an output.
.IP \fB-B\fP
Does the same as
.B -b
option takes a numeric argument as the size in bytes of the input buffer and
the
.B -B
option does the same for the output buffer, the default for both being 1024
bytes, or one kibibyte (KiB).
.PP
The
.B -s
option takes a numeric argument as the number of bytes to skip into the input
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
but for the output buffer.
.IP \fB-S\fP
Seeks a number of bytes through the output before starting to write from
the input. If the output is a stream, null characters are printed.
.IP \fB-a\fP
Accepts a single literal byte with which the input buffer is padded in the event
of an incomplete read from the input file.
.IP \fB-A\fP
Specifying this option pads the input buffer with null bytes in the event of an
incomplete read. This is equivalent to specifying
.B -a
option takes one argument of one byte in length and pads the input buffer with
that byte in the event that a read doesn't fill the input buffer, and the
.B -A
option takes no arguments and pads with nuls.
The
.B -c
option specifies an amount of reads to make, and if 0 (the default) dj will
continue reading until a partial or empty read.
.PP
On a partial or empty read, dj prints a diagnostic message (unless the
.B -q
option is specified) and exits (unless the
.B -n
option is specified, in which case only two consecutive empty reads will cause
dj to exit).
At exit, usage statistics are printed unless the option
.B -q
is specified a second time. The
.B -H
option will make these diagnostics human-readable.
with a null byte instead of a character.
.IP \fB-c\fP
Specifies a number of reads to make. The default is 0, in which case the
input is read until a partial or empty read is made.
.IP \fB-d\fP
Prints invocation information before program execution as described in the
DIAGNOSTICS section. Each invocation increments the debug level of the
program.
.IP \fB-H\fP
Prints diagnostics messages in a human-readable manner as described in the
DIAGNOSTICS section.
.IP \fB-n\fP
Retries failed reads once before exiting.
.IP \fB-q\fP
Suppresses error messages which print when a read or write is partial or
empty. Each invocation decrements the debug level of the program.
.\"
.SH STANDARD INPUT
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
The
.B -d
option prints all information, user-specified or otherwise, before program
execution.
.PP
When dj exits, by default statistics are printed for input and output to
standard error in the following format:
.PP
.R {records read} {ASCII unit separator} {partial records read}
.R {ASCII record separator} {records written} {ASCII unit separator}
.R {partial records written} {ASCII group separator} {bytes read}
.R {ASCII record separator} {bytes written} {ASCII file separator}
.PP
If the
.B -H
option is specified dj instead uses this following format:
.PP
.R {records read} '+' {partial records read} '>' {records written}
.R '+' {partial records written} ';' {bytes read} '>' {bytes written}
.R {ASCII line feed}
.PP
The
On a partial or empty read, unless the
.B -q
option suppresses error messages which print when a read or write is partial or
empty and when used twice suppresses diagnostic output entirely.
.PP
In non-recoverable errors that don't pertain to dj's read-write cycle, a
diagnostic message is printed and dj exits with the appropriate sysexits(3)
status.
option is specified, a diagnostic message is printed. Then, the program exits
unless the
.B -n
option is specified.
By default, statistics are printed for input and output to the standard error in
the following format:
.RS
{records read} {ASCII unit separator} {partial records read}
{ASCII record separator} {records written} {ASCII unit separator}
{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
option is specified, debug information will be printed at the beginning of
execution. This output contains information regarding how the program was
invoked. The following example is the result of running the program with
.B -d
as the only argument:
.RS
argv0=dj
in=<stdin> ibs=1024 skip=0 align=ff count=0
out=<stdout> obs=1024 seek=0 debug= 3 noerror=0
.RE
In non-recoverable errors that don\(cqt pertain to the read-write cycle, a
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 a specified count, actual byte output may be lower than
expected (the product of the count multiplied by the input block size). If the
is specified along with the
.B -c
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 used this could make data written nonsensical.
.PP
options are specified, this could make written data nonsensical.
.\"
.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
Dj was modeled after the dd utility specified in POSIX but adds additional
features: 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's easy to parse for machines. It also neglects character
conversion, which may be dd's original intent but is irrelevant to its modern
use.
This program was based on the
.BR dd (1p)
utility as specified in POSIX. While character conversion may have been the
original intent of
.BR dd (1p),
it is irrelevant to its modern use. Because of this, this program eschews
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 (C) 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
Copyright \(co 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO
dd(1)
.BR dd (1p)

36
docs/false.1
View File

@ -1,35 +1,35 @@
.\" Copyright (c) 2022, 2024 DTB <trinity@trinity.moe>
.\" Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media>
.\" Copyright (c) 2023–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 FALSE 1
.\"
.TH FALSE 1 2024-06-06 "Bonsai Core Utilites 0.13.11"
.SH NAME
false \(en do nothing, unsuccessfully
.\"
.SH DESCRIPTION
False does nothing regardless of operands or standard input.
False will always return an exit code of 1.
Do nothing regardless of operands or standard input. An exit code of 1 will
always be returned.
.\"
.SH RATIONALE
False exists for the construction of control flow and loops based on a failure.
False functions as described in POSIX.1-2017.
In POSIX.1-2017,
.BR false (1p)
exists for the construction of control flow and loops based on a failure. This
implementation functions as described in that standard.
.\"
.SH AUTHOR
Written by Emma Tebibyte <emma@tebibyte.media>.
Written by Emma Tebibyte
.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
true(1p)
.BR true (1p)

62
docs/fop.1 Normal file
View File

@ -0,0 +1,62 @@
.\" 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 "Bonsai Core Utilites 0.13.11"
.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
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)

74
docs/hru.1
View File

@ -2,56 +2,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
.\"
.TH HRU 1 2024-06-17 "Bonsai Core Utilites 0.13.11"
.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.
Convert counts to higher units.
Byte counts will be read in the form of whole numbers from the standard input
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, hru will exit with
the appropriate error code as defined by sysexits.h(3) and print an error
message.
If encountering non-integer characters in the standard input, the program will
exit with the appropriate error code as defined by
.BR 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.
The GNU project\(cqs
.BR ls (1)
implementation contains a human-readable option (\fB-h\fP) that, when specified,
makes the tool print size information in a format more immediately
readable. This functionality is useful not only in this context, so the decision
was made to split it into a new tool. The original functionality from GNU\(cqs
.BR ls (1)
can be emulated with
.BR 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).
The standard unit prefixes as specified by the
.I Bureau International des Poids et Mesures
.RI ( BIPM )
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 <emma@tebibyte.media>.
Written by Emma Tebibyte
.MT emma@tebibyte.media
.ME .
.\"
.SH COPYRIGHT
Copyright (c) 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later
Copyright \(co 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
GNU
.BR ls (1),
.I The International System of Units (SI) 9th Edition

125
docs/intcmp.1
View File

@ -1,78 +1,105 @@
.\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe>
.\" Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media>
.\" Copyright (c) 2023–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 intcmp 1
.\"
.TH INTCMP 1 2024-06-06 "Bonsai Core Utilites 0.13.11"
.SH NAME
intcmp \(en compare integers
.\"
.SH SYNOPSIS
intcmp
.RB ( -eghl )
.RB ( -egl )
.RB [ integer ]
.RB [ integer... ]
.SH DESCRIPTION
Compare integers to each other.
.\"
.SH OPTIONS
Intcmp compares integers.
.SH USAGE
The -e option permits given integers to be equal to each other. If combined
with -g or -l, only adjacent integers in the argument sequence can be equal.
.PP
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".
.IP \fB-e\fP
Permits given integers to be equal to each other.
.IP \fB-g\fP
Permits a given integer to be greater than the following integer.
.IP \fB-l\fP
Permits a given integer to be less than the following integer.
.\"
.SH EXAMPLES
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
Intcmp exits 0 for a valid expression and 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.
The program will exit with a successfully for a valid expression and with an
error code of 1 for an invalid expression.
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
There are multiple ways to express compound comparisons; “less than or equal
to” can be -le or -el, for example.
.PP
The inequality comparison is -gl or -lg for “less than or greater than”; this
is elegant but unintuitive.
.PP
-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.
.BR -egl ,
\(lqequal to or less than or greater than\(rq, always exits successfully for
valid program usage and may be abused to function as an integer validator. Use
.BR str (1)
instead.
.\"
.SH CAVEATS
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 test(1). 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).
been
.BR test (1).
This tool also handles string comparisons and file scrutiny. These parts of its
functionality have been broken out into multiple utilities.
This program\(cqs functionality may be performed on a POSIX-compliant system
with
.BR test (1p).
.\"
.SH AUTHOR
Written by DTB <trinity@trinity.moe>.
Written by DTB
.MT trinity@trinity.moe
.ME .
.\"
.SH COPYRIGHT
Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
.\"
Copyright \(co 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/gpl.html>.
.\"
.SH SEE ALSO
strcmp(1), scrut(1), str(1), test(1p)
.BR scrut (1),
.BR strcmp (1),
.BR str (1),
.BR test (1p)

93
docs/mm.1
View File

@ -2,13 +2,11 @@
.\"
.\" 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
.\"
.TH MM 1 2024-06-17 "Bonsai Core Utilites 0.13.11"
.SH NAME
mm \(en middleman
.\"
.SH SYNOPSIS
mm
@ -17,60 +15,59 @@ mm
.RB [ input ])
.RB ( -o
.RB [ output ])
.\"
.SH DESCRIPTION
Mm catenates input files and writes them to the start of each output file.
Catenate input files and write them to the start of each output file or stream.
.\"
.SH OPTIONS
Mm, upon receiving the
.B -a
option, will open subsequent outputs for appending rather than updating.
.PP
The
.B -i
option opens a path as an input. Without any inputs specified mm will use
standard input. Standard input itself can be specified by giving the path '-'.
.PP
The
.B -o
option opens a path as an output. Without any outputs specified mm will use
standard output. Standard output itself can be specified by giving the
path '-'. Standard error itself can be specified with the
.B -e
option.
.PP
The
.B -u
option ensures neither input or output will be buffered.
.PP
The
.B -n
option tells mm to ignore SIGINT signals.
.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
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
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 can no longer be written mm prints a diagnostic message, ceases
writing to that particular output, and if there are more outputs specified,
continues, eventually exiting unsuccessfully.
.PP
On error mm prints a diagnostic message and exits with the appropriate
sysexits.h(3) status.
If an output cannot be written to, an error occurs; however, exiting will be
deferred until writing to any other specified outputs completes.
.SH BUGS
Mm does not truncate existing files, which may lead to unexpected results.
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
Mm was modeled after the cat and tee utilities specified in POSIX.
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 (c) 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
Copyright \(co 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO
cat(1p), dd(1), dj(1), tee(1p)
.BR cat (1p),
.BR dd (1),
.BR dj (1),
.BR tee (1p)

80
docs/npc.1
View File

@ -1,68 +1,74 @@
.\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe>
.\" Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media>
.\" Copyright (c) 2023–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 npc 1
.\"
.TH NPC 1 2024-06-17 "Bonsai Core Utilites 0.13.11"
.SH NAME
npc \(en show non-printing characters
.\"
.SH SYNOPSIS
npc
.RB ( -eht )
.RB ( -et )
.\"
.SH DESCRIPTION
Npc reads from standard input and writes to standard output, replacing non-
printing characters with printable equivalents. Control characters print as a
carat ('^') followed by the character '@' through '_' corresponding to the
character replaced (e.g. control-X becomes "^X"). The delete character (0x7F)
becomes "^?". Characters with the high bit set (>127) are printed as "M-"
Print normally non-printing characters.
The program reads from standard input and writes to standard output, replacing
non-printing characters with printable equivalents. Control characters print as
a carat ('^') followed by the character '@' through '_' corresponding to the
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
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.
.\"
.SH OPTIONS
.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
Npc prints a debug message and exits with the appropriate sysexits(3) error
code in the event of an error, otherwise it exits successfully.
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
Npc operates in single-byte chunks regardless of intended encoding.
The program 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 cat(1p), the -v option, is the
bandage solution GNU and other software suites use.
This functionality should be a separate tool because its usefulness extends
beyond that of cat(1p).
using a standard tool. A popular extension to
.BR cat (1p),
the
.B -v
option, is the bandage solution GNU and other software suites use.
This functionality is included in a separate tool because its usefulness extends
beyond that of
.BR cat (1p).
.\"
.SH AUTHOR
Written by DTB <trinity@trinity.moe>.
Written by DTB
.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
cat(1p), cat-v(1)
.BR cat (1p),
.BR cat-v (1),
.I UNIX Style, or cat -v Considered Harmful
by Rob Pike

92
docs/rpn.1
View File

@ -3,68 +3,84 @@
.\"
.\" 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
.\"
.TH RPN 1 2024-06-17 "Bonsai Core Utilites 0.13.11"
.SH NAME
rpn \(en reverse polish notation evaluation
.\"
.SH SYNOPSIS
rpn
.RB [numbers...]\ [operators...]
.RB [ numbers... ]
.RB [ operators... ]
.\"
.SH DESCRIPTION
Rpn evaluates reverse polish notation expressions either read from the standard
input or parsed from provided arguments. See the STANDARD INPUT section.
Evaluate reverse polish notation.
Upon evaluation, rpn will print the resulting number on the stack to the
standard output. Any further specified numbers will be placed at the end of the
The program evaluates reverse polish notation expressions read either from the
standard input or parsed from provided arguments. See the STANDARD INPUT
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 rpn(7).
For information on for reverse polish notation syntax, see
.BR rpn (7).
.\"
.SH STANDARD INPUT
If arguments are passed to rpn, it interprets them as an expression to be
evaluated. Otherwise, it reads whitespace-delimited numbers and operations from
If arguments are specified, they are interpreted as an expression to be
evaluated. Otherwise, whitespace-delimited numbers and operations are read from
the standard input.
.\"
.SH DIAGNOSTICS
If encountering a syntax error, rpn will exit with the appropriate error code
as defined by sysexits.h(3) and print an error message.
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; 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 IEEE Standard for Floating Point Arithmetic (IEEE 754), floating-point
arithmetic has rounding errors. This is somewhat curbed by using the
machine epsilon as provided by the Rust standard library to which to round
numbers. Because of this, variation is expected in the number of decimal places
rpn can handle based on the platform and hardware of any given machine.
with the
.I IEEE Standard for Floating Point Arithmetic
(\fIIEEE 754\fP), floating-point arithmetic has rounding errors. This is
somewhat curbed by using the machine epsilon as provided by the Rust standard
library to which numbers are rounded. Because of this, variation is expected in
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, bc(1p), is included in the POSIX
standard, but does not accept expressions as arguments; in scripts, any
predefined, non-interactive input must be piped into the program. A dc(1)
pre-dates the standardized bc(1p), the latter originally being a preprocessor
for the former, and was included in UNIX v2 onward. While it implements reverse
polish notation, it still suffers from being unable to accept an expression as
an argument.
An infix notation calculation utility,
.BR bc (1p),
is included in the POSIX standard, but does not accept expressions as arguments;
in scripts, any predefined, non-interactive input must be piped into the
program. A
.BR dc (1)
pre-dates the standardized
.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 <emma@tebibyte.media>.
Written by Emma Tebibyte
.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
bc(1p), dc(1), rpn(7), IEEE 754
.BR bc (1p),
.BR dc (1),
.BR rpn (7),
.I IEEE 754

125
docs/scrut.1
View File

@ -1,93 +1,86 @@
.\" 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
.\"
.TH SCRUT 1 2024-06-06 "Bonsai Core Utilites 0.13.11"
.SH NAME
scrut \(en scrutinize file properties
.SH SYNOPSIS
scrut
.RB ( -bcdefgkprsuwxLS )
.RB ( -LSbcdefgkprsuwx )
.RB [ file... ]
.\"
.SH DESCRIPTION
Scrut determines if given files comply with the opted requirements.
Determine if files comply with requirements. If the given files comply with the
specified requirements, the program will exit successfully. Otherwise, it exits
unsuccessfully.
.\"
.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.
.IP \fB-L\fB
Requires the given files to exist and be symbolic links.
.IP \fB-S\fP
Requires the given files to exist and be sockets.
.IP \fB-b\fP
Requires the given files to exist and be block special files.
.IP \fB-c\fP
Requires the given files to exist and be character special files.
.IP \fB-d\fP
Requires the given files to exist and be directories.
.IP \fB-e\fP
Requires the given files to exist, and is redundant to any other option.
.IP \fB-f\fP
Requires the given files to exist and be regular files.
.IP \fB-g\fP
Requires the given files to exist and have their set group ID flags set.
.IP \fB-k\fP
Requires the given files to exist and have their sticky bit set.
.IP \fB-p\fP
Requires the given files to exist and be named pipes.
.IP \fB-r\fP
Requires the given files to exist and be readable.
.IP \fB-u\fP
Requires the given files to exist and have their set user ID flags set.
.IP \fB-w\fP
Requires the given files to exist and be writable.
.IP \fB-x\fP
Requires the given files to exist and be executable.
.\"
.SH DIAGNOSTICS
.SH EXIT STATUS
When invoked incorrectly, a debug message will be printed and the program will
exit with the appropriate
.BR sysexits.h (3)
error code.
.\"
.SH RATIONALE
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
The
.BR test (1p)
utility contains functionality that was broken out into separate programs. Thus,
the scope of this program is narrower than it. 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>.
Written by DTB
.MT trinity@trinity.moe
.ME .
.\"
.SH COPYRIGHT
Copyright © 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
Copyright \(co 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)
.BR access (3p),
.BR lstat (3p),
.BR test (1p)

66
docs/str.1
View File

@ -1,58 +1,60 @@
.\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe>
.\" Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media>
.\" Copyright (c) 2023–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 STR 1
.\"
.TH STR 1 2024-06-17 "Bonsai Core Utilites 0.13.11"
.SH NAME
str \(en test the character types of string arguments
str \(en test string arguments
.\"
.SH SYNOPSIS
str
.RB [ type ]
.RB [ string... ]
.\"
.SH DESCRIPTION
Str tests each character in an arbitrary quantity of string arguments against
the function of the same name within ctype(3).
Test the character types of string arguments.
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
Str exits successfully if all tests pass and unsuccessfully if a test failed.
.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.
If all tests pass, the program will exit successfully. If any of the tests fail,
the program will exit unsuccessfully with an error code of 1.
.SH DEPRECATED FEATURES
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
Str used to have an "isvalue" type as an extension to ctype(3). This was
removed in favor of using strcmp(1) to compare strings against the empty string
('').
None of an empty string\(cqs contents pass any of the tests, so the program will
exit unsuccessfully if one is specified.
.SH BUGS
There's no way of knowing which argument failed the test without re-testing
There\(cqs 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 <trinity@trinity.moe>.
Written by DTB
.MT trinity@trinity.moe
.ME .
.\"
.SH COPYRIGHT
Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
Copyright \(co 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/gpl.html>.
.\"
.SH SEE ALSO
ctype(3p), strcmp(1), ascii(7)
.BR ctype (3p),
.BR strcmp(1),
.BR ascii(7)

82
docs/strcmp.1
View File

@ -1,62 +1,76 @@
.\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe>
.\" Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media>
.\" Copyright (c) 2023–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 STRCMP 1
.\"
.TH STRCMP 1 2024-06-17 "Bonsai Core Utilites 0.13.11"
.SH NAME
strcmp \(en compare strings
.\"
.SH SYNOPSIS
strcmp
.RM [ string ]
.RB [ strings... ]
.\"
.SH DESCRIPTION
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
).
Check whether string arguments are the same.
.\"
.SH DIAGNOSTICS
Strcmp will print an error message and exit unsuccessfully with a status
described in sysexits(3) if used incorrectly (given less than two operands).
The program will exit successfully if the strings are identical. Otherwise, it
will exit with an error code of 1 if a string passed has a lesser byte value
than one of the prior strings:
.SH UNICODE
.RS
strcmp b a
.RE
Strcmp will exit unsuccessfully if the given strings are not identical;
Unicode strings may need to be normalized if the intent is to check visual
similarity and not byte similarity.
or with an error code of 255 if it has a greater byte value than one of the
prior strings:
.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 test(1). 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).
been
.BR test (1).
This tool also handles integer comparisons and file scrutiny. These parts of its
functionality have been broken out into multiple utilities.
This program\(cqs functionality may be performed on a POSIX-compliant system
with
.BR test (1p).
.\"
.SH AUTHOR
Written by DTB <trinity@trinity.moe>.
Written by DTB
.MT trinity@trinity.moe
.ME .
.\"
.SH COPYRIGHT
Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
Copyright \(co 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/gpl.html>.
.\"
.SH SEE ALSO
strcmp(3), intcmp(1), scrut(1), test(1p)
.BR strcmp (3),
.BR intcmp (1),
.BR scrut (1),
.BR test (1p)

90
docs/swab.1
View File

@ -1,14 +1,13 @@
.\" 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
.\"
.TH SWAB 1 2024-06-17 "Bonsai Core Utilites 0.13.11"
.SH NAME
swab \(en swap bytes
.\"
.SH SYNOPSIS
swab
@ -17,55 +16,66 @@ swab
.R [
.B word size
.R ])
.\"
.SH DESCRIPTION
.SH USAGE
Swab swaps the latter and former halves of a block of bytes.
Swap the latter and former halves of a block of bytes.
.\"
.SH OPTIONS
.IP \fB-f\fP
Ignore SIGINT signal.
.IP \fB-w\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 sh(1p) line:
The following
.BR sh (1p)
line:
.R printf 'hello world!\n' | swab
.RS
printf 'hello world!\(rsn' | swab
.RE
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.
.RS
ehll oowlr!d
.RE
.\"
.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).
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
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.
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 (c) 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
Copyright \(co 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO
dd(1p)
.BR dd (1p)

37
docs/true.1
View File

@ -1,35 +1,36 @@
.\" Copyright (c) 2022, 2024 DTB <trinity@trinity.moe>
.\" Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media>
.\" Copyright (c) 2023–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 TRUE 1
.\"
.TH TRUE 1 2024-06-06 "Bonsai Core Utilites 0.13.11"
.SH NAME
true \(en do nothing, successfully
.\"
.SH DESCRIPTION
True does nothing regardless of operands or standard input.
True will always return an exit code of 0.
Do nothing regardless of operands or standard input. An exit code of 0 will
always be returned.
.\"
.SH RATIONALE
True exists for the construction of control flow and loops based on a success.
True functions as described in POSIX.1-2017.
In \fIPOSIX.1-2017\fP,
.BR true (1p)
exists for the construction of control flow and loops based on a success. This
implementation functions as described in that standard.
.\"
.SH AUTHOR
Written by Emma Tebibyte <emma@tebibyte.media>.
Written by Emma Tebibyte
.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
false(1p)
.BR false (1p),
.BR true (1p)

5
src/fop.rs
View File

@ -32,12 +32,13 @@ use sysexits::{ EX_DATAERR, EX_IOERR, EX_UNAVAILABLE, EX_USAGE };
fn main() {
let argv = args().collect::<Vec<String>>();
let mut d = '␞';
let mut d = '\u{1E}'.to_string();
let usage = format!(
"Usage: {} [-d delimiter] index command [args...]",
argv[0],
);
let mut index_arg = 0;
let mut arg_parser = Parser::new(&argv, "d:");
while let Some(opt) = argv.getopt("d:") {
match opt {
@ -73,7 +74,7 @@ fn main() {
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()

18
src/mm.c
View File

@ -106,6 +106,15 @@ oserr(char *s, char *r){
} \
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} */
@ -178,12 +187,15 @@ int main(int argc, char *argv[]){
k = 1;
break;
default:
fprintf(stderr, "Usage: %s (-aenu) (-i [input])..."
" (-o [output])...\n", argv[0]);
retval = EX_USAGE;
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;

15
src/scrut.c
View File

@ -1,5 +1,6 @@
/*
* Copyright (c) 2023 DTB <trinity@trinity.moe>
* Copyright (c) 2023–2024 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
@ -17,13 +18,15 @@
*/
#include <stdio.h> /* fprintf(3), stderr, NULL */
#include <stdlib.h> /* EXIT_FAILURE */
#include <stdlib.h> /* EXIT_FAILURE, EXIT_SUCCESS */
#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)];
@ -57,7 +60,7 @@ int main(int argc, char *argv[]){
argv += optind;
do{ if(access(*argv, F_OK) != 0 || lstat(*argv, &buf) == -1)
return 1; /* doesn't exist or isn't stattable */
return EXIT_FAILURE; /* doesn't exist or isn't stattable */
for(i = 0; ops[i] != '\0'; ++i)
if(ops[i] == 'e')
@ -97,8 +100,8 @@ usage: fprintf(stderr, "Usage: %s (-%s) [file...]\n",
&& !S_ISLNK(buf.st_mode))
|| (ops[i] == 'S'
&& !S_ISSOCK(buf.st_mode)))
return 1;
return EXIT_FAILURE;
}while(*++argv != NULL);
return 0;
return EXIT_SUCCESS;
}

10
src/test.rs
View File

@ -1,10 +0,0 @@
extern crate strerror;
use strerror::raw_message;
fn main() {
stdout.write_all(b"meow\n").unwrap_or_else(|e| {
eprintln!("{}", raw_message(e));
std::process::exit(1);
});
}