bonsai/harakit
5
4
Fork 3
Code Issues 41 Pull Requests 7 Projects 1 Releases 30 Activity

Merge branch 'main' into peek

Browse Source
This commit is contained in:
dtb 2024-06-26 09:40:59 -06:00
commit 262b3c18fb
21 changed files with 824 additions and 568 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 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 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 copyright holders for the file. For example, an existing copyright header might

19
Makefile
View File

@ -8,15 +8,16 @@
# permitted in any medium without royalty provided the copyright notice and this # permitted in any medium without royalty provided the copyright notice and this
# notice are preserved. This file is offered as-is, without any warranty. # 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 .POSIX:
.PRAGMA: posix_202x # future POSIX standard support à la pdpmake(1)
.PRAGMA: command_comment # breaks without this?
DESTDIR ?= dist DESTDIR ?= dist
PREFIX ?= /usr/local 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' \ SYSEXITS != printf '\043include <sysexits.h>\n' | cpp -M - | sed 's/ /\n/g' \
| sed -n 's/sysexits\.h//p' || printf 'include\n' | sed -n 's/sysexits\.h//p' || printf 'include\n'
@ -30,9 +31,9 @@ CFLAGS += -I$(SYSEXITS)
.PHONY: all .PHONY: all
all: dj false fop hru intcmp mm npc rpn scrut str strcmp swab true 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: 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 mkdir -p build/bin build/include build/lib build/o build/test
.PHONY: clean .PHONY: clean
@ -42,7 +43,7 @@ clean:
dist: all dist: all
mkdir -p $(DESTDIR)/$(PREFIX)/bin $(DESTDIR)/$(PREFIX)/share/man/man1 mkdir -p $(DESTDIR)/$(PREFIX)/bin $(DESTDIR)/$(PREFIX)/share/man/man1
cp build/bin/* $(DESTDIR)/$(PREFIX)/bin cp build/bin/* $(DESTDIR)/$(PREFIX)/bin
cp docs/*.1 $(DESTDIR)/$(PREFIX)/share/man/man1 cp docs/*.1 $(DESTDIR)/$(PREFIX)/$(MANDIR)/man1
.PHONY: install .PHONY: install
install: dist install: dist
@ -65,9 +66,9 @@ build/o/libstrerror.rlib: build src/strerror.rs
$(RUSTC) $(RUSTFLAGS) --crate-type=lib -o $@ \ $(RUSTC) $(RUSTFLAGS) --crate-type=lib -o $@ \
src/strerror.rs src/strerror.rs
# bandage solution until bindgen(1) gets stdin support
build/o/libsysexits.rlib: build $(SYSEXITS)sysexits.h build/o/libsysexits.rlib: build $(SYSEXITS)sysexits.h
# bandage solution until bindgen(1) gets stdin support printf '\043define EXIT_FAILURE 1\n' | cat - $(SYSEXITS)sysexits.h \
printf '#define EXIT_FAILURE 1\n' | cat - $(SYSEXITS)sysexits.h \
> build/include/sysexits.h > build/include/sysexits.h
bindgen --default-macro-constant-type signed --use-core --formatter=none \ bindgen --default-macro-constant-type signed --use-core --formatter=none \
build/include/sysexits.h | $(RUSTC) $(RUSTFLAGS) --crate-type lib -o $@ - build/include/sysexits.h | $(RUSTC) $(RUSTFLAGS) --crate-type lib -o $@ -

16
README
View File

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

255
docs/dj.1
View File

@ -1,14 +1,13 @@
.\" Copyright (c) 2024 DTB <trinity@trinity.moe> .\" 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, .\" 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/>. .\" 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 .SH NAME
dj \(en disk jockey dj \(en disk jockey
.\"
.SH SYNOPSIS .SH SYNOPSIS
dj dj
@ -19,142 +18,172 @@ dj
.RB [ count ]) .RB [ count ])
.RB ( -i .RB ( -i
.R [ [\fBinput file\fP])
.B input file
.R ])
.RB ( -b .RB ( -b
.R [ [\fBinput block size\fP])
.B input block size
.R ])
.RB ( -s .RB ( -s
.R [ [\fBinput offset\fP])
.B input offset
.R ])
.RB ( -o .RB ( -o
.R [ [\fBoutput file\fP])
.B output file
.R ])
.RB ( -B .RB ( -B
.R [ [\fBoutput block size\fP])
.B output block size
.R ])
.RB ( -S .RB ( -S
.R [ [\fBoutput offset\fP])
.B output offset .\"
.R ]) .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 This manual page uses the terms \(lqskip\(rq and \(lqseek\(rq to refer to moving
.B -i to a specified byte by index in the input and output of the program
option takes a path as an argument to open and use in place of standard input. respectively. This language is inherited from the
The .BR dd (1p)
.B -o utility and used here to decrease ambiguity.
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. When seeking or skipping to a byte, writing or reading starts at the byte
.PP immediately subsequent to the specified byte.
The .\"
.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 .B -b
option takes a numeric argument as the size in bytes of the input buffer and but for the output buffer.
the .IP \fB-S\fP
.B -B Seeks a number of bytes through the output before starting to write from
option does the same for the output buffer, the default for both being 1024 the input. If the output is a stream, null characters are printed.
bytes, or one kibibyte (KiB). .IP \fB-a\fP
.PP Accepts a single literal byte with which the input buffer is padded in the event
The of an incomplete read from the input file.
.B -s .IP \fB-A\fP
option takes a numeric argument as the number of bytes to skip into the input Specifying this option pads the input buffer with null bytes in the event of an
before starting to read, and the incomplete read. This is equivalent to specifying
.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 .B -a
option takes one argument of one byte in length and pads the input buffer with with a null byte instead of a character.
that byte in the event that a read doesn't fill the input buffer, and the .IP \fB-c\fP
.B -A Specifies a number of reads to make. The default is 0, in which case the
option takes no arguments and pads with nuls. input is read until a partial or empty read is made.
The .IP \fB-d\fP
.B -c Prints invocation information before program execution as described in the
option specifies an amount of reads to make, and if 0 (the default) dj will DIAGNOSTICS section. Each invocation increments the debug level of the
continue reading until a partial or empty read. program.
.PP .IP \fB-H\fP
On a partial or empty read, dj prints a diagnostic message (unless the Prints diagnostics messages in a human-readable manner as described in the
.B -q DIAGNOSTICS section.
option is specified) and exits (unless the .IP \fB-n\fP
.B -n Retries failed reads once before exiting.
option is specified, in which case only two consecutive empty reads will cause .IP \fB-q\fP
dj to exit). Suppresses error messages which print when a read or write is partial or
At exit, usage statistics are printed unless the option empty. Each invocation decrements the debug level of the program.
.B -q .\"
is specified a second time. The .SH STANDARD INPUT
.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 .SH DIAGNOSTICS
The On a partial or empty read, unless 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
.B -q .B -q
option suppresses error messages which print when a read or write is partial or option is specified, a diagnostic message is printed. Then, the program exits
empty and when used twice suppresses diagnostic output entirely. unless the
.PP .B -n
In non-recoverable errors that don't pertain to dj's read-write cycle, a option is specified.
diagnostic message is printed and dj exits with the appropriate sysexits(3)
status.
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 .SH BUGS
If If
.B -n .B -n
is specified along with a specified count, actual byte output may be lower than is specified along with the
expected (the product of the count multiplied by the input block size). If 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 .B -a
or or
.B -A .B -A
options are used this could make data written nonsensical. options are specified, this could make written data 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 Many lowercase options have capitalized variants and vice-versa which can be
confusing. Capitalized options tend to affect output or are more intense confusing. Capitalized options tend to affect output or are more intense
versions of lowercase options. versions of lowercase options.
.\"
.SH RATIONALE .SH RATIONALE
Dj was modeled after the dd utility specified in POSIX but adds additional This program was based on the
features: typical option formatting, allowing seeks to be specified in bytes .BR dd (1p)
rather than in blocks, allowing arbitrary bytes as padding, and printing in a utility as specified in POSIX. While character conversion may have been the
format that's easy to parse for machines. It also neglects character original intent of
conversion, which may be dd's original intent but is irrelevant to its modern .BR dd (1p),
use. 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 .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>. <https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO .SH SEE ALSO
.BR dd (1p)
dd(1)

36
docs/false.1
View File

@ -1,35 +1,35 @@
.\" Copyright (c) 2022, 2024 DTB <trinity@trinity.moe> .\" 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, .\" 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/>. .\" 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 .SH NAME
false \(en do nothing, unsuccessfully false \(en do nothing, unsuccessfully
.\"
.SH DESCRIPTION .SH DESCRIPTION
False does nothing regardless of operands or standard input. Do nothing regardless of operands or standard input. An exit code of 1 will
False will always return an exit code of 1. always be returned.
.\"
.SH RATIONALE .SH RATIONALE
False exists for the construction of control flow and loops based on a failure. In POSIX.1-2017,
.BR false (1p)
False functions as described in POSIX.1-2017. exists for the construction of control flow and loops based on a failure. This
implementation functions as described in that standard.
.\"
.SH AUTHOR .SH AUTHOR
Written by Emma Tebibyte <emma@tebibyte.media>. Written by Emma Tebibyte
.MT emma@tebibyte.media
.ME .
.\"
.SH COPYRIGHT .SH COPYRIGHT
This work is marked with CC0 1.0. To see a copy of this license, visit This work is marked with CC0 1.0. To see a copy of this license, visit
<http://creativecommons.org/publicdomain/zero/1.0>. <http://creativecommons.org/publicdomain/zero/1.0>.
.\"
.SH SEE ALSO .SH SEE ALSO
.BR true (1p)
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, .\" 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/>. .\" 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 .SH NAME
hru \(en human readable units hru \(en human readable units
.\"
.SH SYNOPSIS .SH SYNOPSIS
hru hru
.\"
.SH DESCRIPTION .SH DESCRIPTION
Hru reads byte counts in the form of whole numbers from the standard input and Convert counts to higher units.
writes to the standard output the same number converted one of the units of data
defined by the International System of 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 The program will convert the byte count to the highest unit possible where the
value is greater than one. value is greater than one.
.\"
.SH DIAGNOSTICS .SH DIAGNOSTICS
If encountering non-integer characters in the standard input, hru will exit with If encountering non-integer characters in the standard input, the program will
the appropriate error code as defined by sysexits.h(3) and print an error exit with the appropriate error code as defined by
message. .BR sysexits.h (3)
and print an error message.
.\"
.SH RATIONALE .SH RATIONALE
The GNU project’s ls(1) implementation contains a human-readable option (-h) The GNU project\(cqs
that, when specified, makes the tool print size information in a format more .BR ls (1)
immediately readable. This functionality is useful not only in the context of implementation contains a human-readable option (\fB-h\fP) that, when specified,
ls(1) so the decision was made to split it into a new tool. The original makes the tool print size information in a format more immediately
functionality in GNU’s ls(1) can be emulated with fop(1) combined with this readable. This functionality is useful not only in this context, so the decision
program. 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 .SH STANDARDS
Hru follows the standard unit prefixes as specified by the Bureau International The standard unit prefixes as specified by the
des Poids et Mesures (BIPM) in the ninth edition of The International System of .I Bureau International des Poids et Mesures
Units (SI). .RI ( BIPM )
in the ninth edition of
.I The International System of Units
.RI ( SI )
are utilized for the ouput of conversions.
.\"
.SH AUTHOR .SH AUTHOR
Written by Emma Tebibyte <emma@tebibyte.media>. Written by Emma Tebibyte
.MT emma@tebibyte.media
.ME .
.\"
.SH COPYRIGHT .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>. <https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO .SH SEE ALSO
GNU
GNU ls(1), The International System of Units (SI) 9th Edition .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–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, .\" 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/>. .\" 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 .SH NAME
intcmp \(en compare integers intcmp \(en compare integers
.\"
.SH SYNOPSIS .SH SYNOPSIS
intcmp intcmp
.RB ( -eghl ) .RB ( -egl )
.RB [ integer ] .RB [ integer ]
.RB [ integer... ] .RB [ integer... ]
.SH DESCRIPTION .SH DESCRIPTION
Compare integers to each other.
.\"
.SH OPTIONS
Intcmp compares integers. .IP \fB-e\fP
Permits given integers to be equal to each other.
.SH USAGE .IP \fB-g\fP
Permits a given integer to be greater than the following integer.
The -e option permits given integers to be equal to each other. If combined .IP \fB-l\fP
with -g or -l, only adjacent integers in the argument sequence can be equal. Permits a given integer to be less than the following integer.
.PP .\"
The -g option permits a given integer to be greater than the following integer. .SH EXAMPLES
.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 .SH DIAGNOSTICS
Intcmp exits 0 for a valid expression and 1 for an invalid expression. The program will exit with a successfully for a valid expression and with an
.PP error code of 1 for an invalid expression.
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 .SH BUGS
There are multiple ways to express compound comparisons; “less than or equal .BR -egl ,
to” can be -le or -el, for example. \(lqequal to or less than or greater than\(rq, always exits successfully for
.PP valid program usage and may be abused to function as an integer validator. Use
The inequality comparison is -gl or -lg for “less than or greater than”; this .BR str (1)
is elegant but unintuitive. instead.
.PP .\"
-egl, "equal to or less than or greater than", exits 0 no matter what for valid .SH CAVEATS
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 .SH RATIONALE
The traditional tool for integer comparisons in POSIX and other Unix shells has 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. been
These parts of its functionality have been broken out into multiple utilities. .BR test (1).
This tool also handles string comparisons and file scrutiny. These parts of its
Strcmp’s functionality may be performed on a POSIX-compliant system with functionality have been broken out into multiple utilities.
test(1p).
This program\(cqs functionality may be performed on a POSIX-compliant system
with
.BR test (1p).
.\"
.SH AUTHOR .SH AUTHOR
Written by DTB <trinity@trinity.moe>. Written by DTB
.MT trinity@trinity.moe
.ME .
.\"
.SH COPYRIGHT .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>. <https://gnu.org/licenses/gpl.html>.
.\"
.SH SEE ALSO .SH SEE ALSO
.BR scrut (1),
strcmp(1), scrut(1), str(1), test(1p) .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, .\" 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/>. .\" 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 .SH NAME
mm \(en middleman mm \(en middleman
.\"
.SH SYNOPSIS .SH SYNOPSIS
mm mm
@ -17,60 +15,59 @@ mm
.RB [ input ]) .RB [ input ])
.RB ( -o .RB ( -o
.RB [ output ]) .RB [ output ])
.\"
.SH DESCRIPTION .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 .SH OPTIONS
Mm, upon receiving the .IP \fB-a\fP
.B -a Opens subsequent outputs for appending rather than updating.
option, will open subsequent outputs for appending rather than updating. .IP \fB-e\fP
.PP Use the standard error as an output.
The .IP \fB-i\fP
.B -i Opens a path as an input. If one or more of the input files is \(lq-\(rq or if
option opens a path as an input. Without any inputs specified mm will use no inputs are specified, the standard input shall be used.
standard input. Standard input itself can be specified by giving the path '-'. .IP \fB-o\fP
.PP Opens a path as an output. If one or more of the output files is \(lq-\(rq or if
The no outputs are specified, the standard output shall be used.
.B -o .IP \fB-u\fP
option opens a path as an output. Without any outputs specified mm will use Ensures neither input or output will be buffered.
standard output. Standard output itself can be specified by giving the .IP \fB-n\fP
path '-'. Standard error itself can be specified with the Causes SIGINT signals to be ignored.
.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.
.SH DIAGNOSTICS .SH DIAGNOSTICS
If an output can no longer be written mm prints a diagnostic message, ceases If an output cannot be written to, an error occurs; however, exiting will be
writing to that particular output, and if there are more outputs specified, deferred until writing to any other specified outputs completes.
continues, eventually exiting unsuccessfully.
.PP
On error mm prints a diagnostic message and exits with the appropriate
sysexits.h(3) status.
.SH BUGS When an error is encountered, a diagnostic message is printed and the program
exits with the appropriate
Mm does not truncate existing files, which may lead to unexpected results. .BR sysexits.h (3)
status.
.\"
.SH CAVEATS
Existing files are not truncated on ouput and are instead overwritten.
.\"
.SH RATIONALE .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 .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>. <https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO .SH SEE ALSO
.BR cat (1p),
cat(1p), dd(1), dj(1), tee(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–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, .\" 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/>. .\" 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 .SH NAME
npc \(en show non-printing characters npc \(en show non-printing characters
.\"
.SH SYNOPSIS .SH SYNOPSIS
npc npc
.RB ( -eht ) .RB ( -et )
.\"
.SH DESCRIPTION .SH DESCRIPTION
Npc reads from standard input and writes to standard output, replacing non- Print normally non-printing characters.
printing characters with printable equivalents. Control characters print as a
carat ('^') followed by the character '@' through '_' corresponding to the The program reads from standard input and writes to standard output, replacing
character replaced (e.g. control-X becomes "^X"). The delete character (0x7F) non-printing characters with printable equivalents. Control characters print as
becomes "^?". Characters with the high bit set (>127) are printed as "M-" 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 followed by the graphical representation for the same character without the
high bit set. high bit set.
.PP .\"
The .SH OPTIONS
.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 .SH DIAGNOSTICS
Npc prints a debug message and exits with the appropriate sysexits(3) error In the event of an error, a debug message will be printed and the program will
code in the event of an error, otherwise it exits successfully. exit with the appropriate
.BR sysexits.h (3)
error code.
.\"
.SH BUGS .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 .SH RATIONALE
POSIX currently lacks a way to display non-printing characters in the terminal 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 using a standard tool. A popular extension to
bandage solution GNU and other software suites use. .BR cat (1p),
the
This functionality should be a separate tool because its usefulness extends .B -v
beyond that of cat(1p). 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 .SH AUTHOR
Written by DTB <trinity@trinity.moe>. Written by DTB
.MT trinity@trinity.moe
.ME .
.\"
.SH COPYRIGHT .SH COPYRIGHT
Copyright © 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/agpl.html>. <https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO .SH SEE ALSO
.BR cat (1p),
cat(1p), cat-v(1) .BR cat-v (1),
.I UNIX Style, or cat -v Considered Harmful .I UNIX Style, or cat -v Considered Harmful
by Rob Pike 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, .\" 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/>. .\" 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 .SH NAME
rpn \(en reverse polish notation evaluation rpn \(en reverse polish notation evaluation
.\"
.SH SYNOPSIS .SH SYNOPSIS
rpn rpn
.RB [numbers...]\ [operators...] .RB [ numbers... ]
.RB [ operators... ]
.\"
.SH DESCRIPTION .SH DESCRIPTION
Rpn evaluates reverse polish notation expressions either read from the standard Evaluate reverse polish notation.
input or parsed from provided arguments. See the STANDARD INPUT section.
Upon evaluation, rpn will print the resulting number on the stack to the The program evaluates reverse polish notation expressions read either from the
standard output. Any further specified numbers will be placed at the end of 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. 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 .SH STANDARD INPUT
If arguments are passed to rpn, it interprets them as an expression to be If arguments are specified, they are interpreted as an expression to be
evaluated. Otherwise, it reads whitespace-delimited numbers and operations from evaluated. Otherwise, whitespace-delimited numbers and operations are read from
the standard input. the standard input.
.\"
.SH DIAGNOSTICS .SH DIAGNOSTICS
If encountering a syntax error, rpn will exit with the appropriate error code In the event of an error, a debug message will be printed and the program will
as defined by sysexits.h(3) and print an error message. 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 .SH CAVEATS
Due to precision constraints and the way floats are represented in accordance Due to precision constraints and the way floats are represented in accordance
with the IEEE Standard for Floating Point Arithmetic (IEEE 754), floating-point with the
arithmetic has rounding errors. This is somewhat curbed by using the .I IEEE Standard for Floating Point Arithmetic
machine epsilon as provided by the Rust standard library to which to round (\fIIEEE 754\fP), floating-point arithmetic has rounding errors. This is
numbers. Because of this, variation is expected in the number of decimal places somewhat curbed by using the machine epsilon as provided by the Rust standard
rpn can handle based on the platform and hardware of any given machine. 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 .SH RATIONALE
An infix notation calculation utility, bc(1p), is included in the POSIX An infix notation calculation utility,
standard, but does not accept expressions as arguments; in scripts, any .BR bc (1p),
predefined, non-interactive input must be piped into the program. A dc(1) is included in the POSIX standard, but does not accept expressions as arguments;
pre-dates the standardized bc(1p), the latter originally being a preprocessor in scripts, any predefined, non-interactive input must be piped into the
for the former, and was included in UNIX v2 onward. While it implements reverse program. A
polish notation, it still suffers from being unable to accept an expression as .BR dc (1)
an argument. 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 .SH AUTHOR
Written by Emma Tebibyte <emma@tebibyte.media>. Written by Emma Tebibyte
.MT emma@tebibyte.media
.ME .
.\"
.SH COPYRIGHT .SH COPYRIGHT
Copyright (c) 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>. <https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO .SH SEE ALSO
.BR bc (1p),
bc(1p), dc(1), rpn(7), IEEE 754 .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 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, .\" 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/>. .\" 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 .SH NAME
scrut \(en scrutinize file properties scrut \(en scrutinize file properties
.SH SYNOPSIS .SH SYNOPSIS
scrut scrut
.RB ( -bcdefgkprsuwxLS ) .RB ( -LSbcdefgkprsuwx )
.RB [ file... ] .RB [ file... ]
.\"
.SH DESCRIPTION .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 .SH OPTIONS
.B -b .IP \fB-L\fB
requires the given files to exist and be block special files. Requires the given files to exist and be symbolic links.
.PP .IP \fB-S\fP
.B -c Requires the given files to exist and be sockets.
requires the given files to exist and be character special files. .IP \fB-b\fP
.PP Requires the given files to exist and be block special files.
.B -d .IP \fB-c\fP
requires the given files to exist and be directories. Requires the given files to exist and be character special files.
.PP .IP \fB-d\fP
.B -e Requires the given files to exist and be directories.
requires the given files to exist, and is redundant to any other option. .IP \fB-e\fP
.PP Requires the given files to exist, and is redundant to any other option.
.B -e .IP \fB-f\fP
requires the given files to exist and be regular files. Requires the given files to exist and be regular files.
.PP .IP \fB-g\fP
.B -g Requires the given files to exist and have their set group ID flags set.
requires the given files to exist and have their set group ID flags set. .IP \fB-k\fP
.PP Requires the given files to exist and have their sticky bit set.
.B -k .IP \fB-p\fP
requires the given files to exist and have their sticky bit set. Requires the given files to exist and be named pipes.
.PP .IP \fB-r\fP
.B -p Requires the given files to exist and be readable.
requires the given files to exist and be named pipes. .IP \fB-u\fP
.PP Requires the given files to exist and have their set user ID flags set.
.B -r .IP \fB-w\fP
requires the given files to exist and be readable. Requires the given files to exist and be writable.
.PP .IP \fB-x\fP
.B -u Requires the given files to exist and be executable.
requires the given files to exist and have their set user ID flags set. .\"
.PP .SH DIAGNOSTICS
.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 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 The
sysexits.h(3) error code if invoked incorrectly. Scrut exits successfully if .BR test (1p)
the given files comply with their requirements and unsuccessfully otherwise. utility contains functionality that was broken out into separate programs. Thus,
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 .B -h
option is now invalid and therefore shows usage information instead of being an option is now invalid and therefore shows usage information instead of being an
alias to the modern alias to the modern
.B -L .B -L
option. option.
.\"
.SH AUTHOR .SH AUTHOR
Written by DTB <trinity@trinity.moe>. Written by DTB
.MT trinity@trinity.moe
.ME .
.\"
.SH COPYRIGHT .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>. <https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO .SH SEE ALSO
.BR access (3p),
access(3p), lstat(3p), test(1p) .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–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, .\" 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/>. .\" 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 .SH NAME
str \(en test string arguments
str \(en test the character types of string arguments .\"
.SH SYNOPSIS .SH SYNOPSIS
str str
.RB [ type ] .RB [ type ]
.RB [ string... ] .RB [ string... ]
.\"
.SH DESCRIPTION .SH DESCRIPTION
Str tests each character in an arbitrary quantity of string arguments against Test the character types of string arguments.
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 .SH DIAGNOSTICS
Str exits successfully if all tests pass and unsuccessfully if a test failed. If all tests pass, the program will exit successfully. If any of the tests fail,
.PP the program will exit unsuccessfully with an error code of 1.
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.
.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 None of an empty string\(cqs contents pass any of the tests, so the program will
removed in favor of using strcmp(1) to compare strings against the empty string exit unsuccessfully if one is specified.
('').
.SH BUGS There\(cqs no way of knowing which argument failed the test without re-testing
There's no way of knowing which argument failed the test without re-testing
arguments individually. 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 .SH AUTHOR
Written by DTB <trinity@trinity.moe>. Written by DTB
.MT trinity@trinity.moe
.ME .
.\"
.SH COPYRIGHT .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>. <https://gnu.org/licenses/gpl.html>.
.\"
.SH SEE ALSO .SH SEE ALSO
.BR ctype (3p),
ctype(3p), strcmp(1), ascii(7) .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–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, .\" 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/>. .\" 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 .SH NAME
strcmp \(en compare strings strcmp \(en compare strings
.\"
.SH SYNOPSIS .SH SYNOPSIS
strcmp strcmp
.RM [ string ] .RM [ string ]
.RB [ strings... ] .RB [ strings... ]
.\"
.SH DESCRIPTION .SH DESCRIPTION
Strcmp checks whether the given strings are the same. Check whether string arguments 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 .SH DIAGNOSTICS
Strcmp will print an error message and exit unsuccessfully with a status The program will exit successfully if the strings are identical. Otherwise, it
described in sysexits(3) if used incorrectly (given less than two operands). 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; or with an error code of 255 if it has a greater byte value than one of the
Unicode strings may need to be normalized if the intent is to check visual prior strings:
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 .SH RATIONALE
The traditional tool for string comparisons in POSIX and other Unix shells has 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. been
These parts of its functionality have been broken out into multiple utilities. .BR test (1).
This tool also handles integer comparisons and file scrutiny. These parts of its
Strcmp’s functionality may be performed on a POSIX-compliant system with functionality have been broken out into multiple utilities.
test(1p).
This program\(cqs functionality may be performed on a POSIX-compliant system
with
.BR test (1p).
.\"
.SH AUTHOR .SH AUTHOR
Written by DTB <trinity@trinity.moe>. Written by DTB
.MT trinity@trinity.moe
.ME .
.\"
.SH COPYRIGHT .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>. <https://gnu.org/licenses/gpl.html>.
.\"
.SH SEE ALSO .SH SEE ALSO
.BR strcmp (3),
strcmp(3), intcmp(1), scrut(1), test(1p) .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 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, .\" 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/>. .\" 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 .SH NAME
swab \(en swap bytes swab \(en swap bytes
.\"
.SH SYNOPSIS .SH SYNOPSIS
swab swab
@ -17,55 +16,66 @@ swab
.R [ .R [
.B word size .B word size
.R ]) .R ])
.\"
.SH DESCRIPTION
.SH USAGE Swap the latter and former halves of a block of bytes.
.\"
Swab swaps 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 .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: Produces the following output:
.R ehll oowlr!d .RS
ehll oowlr!d
.SH OPTIONS .RE
.\"
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 .SH DIAGNOSTICS
If an error is encountered in input, output, or invocation, a diagnostic In the event of an error, a debug message will be printed and the program will
message will be written to standard error and swab will exit with the exit with the appropriate
appropriate status from sysexits.h(3). .BR sysexits.h (3)
error code.
.\"
.SH RATIONALE .SH RATIONALE
Swab was modeled after the This program was modeled and named after the
.R conv=swab .B conv=swab
functionality specified in the POSIX dd utility but additionally allows the functionality specified
word size to be configured. in the
.PP .BR dd (1p)
Swab is useful for fixing the endianness of binary files produced on other utility. It additionally allows the word size to be configured.
machines.
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 .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>. <https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO .SH SEE ALSO
.BR dd (1p)
dd(1p)

37
docs/true.1
View File

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

12
src/fop.rs
View File

@ -32,18 +32,12 @@ use sysexits::{ EX_DATAERR, EX_IOERR, EX_UNAVAILABLE, EX_USAGE };
fn main() { fn main() {
let argv = args().collect::<Vec<String>>(); let argv = args().collect::<Vec<String>>();
let mut d = '␞'; let mut d = '\u{1E}'.to_string();
let mut arg_parser = Parser::new(&argv, "d:"); let mut arg_parser = Parser::new(&argv, "d:");
while let Some(opt) = arg_parser.next() { while let Some(opt) = arg_parser.next() {
match opt { match opt {
Ok(Opt('d', Some(arg))) => { Ok(Opt('d', Some(arg))) => d = arg,
let arg_char = arg.chars().collect::<Vec<char>>();
if arg_char.len() > 1 {
eprintln!("{}: {}: Not a character.", argv[0], arg);
exit(EX_USAGE);
} else { d = arg_char[0]; }
},
_ => {}, _ => {},
}; };
} }
@ -63,7 +57,7 @@ fn main() {
let mut buf = String::new(); let mut buf = String::new();
let _ = stdin().read_to_string(&mut buf); 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 let opts = argv
.iter() .iter()

18
src/mm.c
View File

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

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 * SPDX-License-Identifier: AGPL-3.0-or-later
* *
* This program is free software: you can redistribute it and/or modify it under * 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 <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) */ #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 <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, #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_ISFIFO, S_ISGID, S_ISREG, S_ISLNK, S_ISSOCK,
* S_ISUID, S_ISVTX */ * S_ISUID, S_ISVTX */
#include <sysexits.h>
static char args[] = "bcdefghkprsuwxLS"; static char args[] = "bcdefghkprsuwxLS";
static char ops[(sizeof args) / (sizeof *args)]; static char ops[(sizeof args) / (sizeof *args)];
@ -57,7 +60,7 @@ int main(int argc, char *argv[]){
argv += optind; argv += optind;
do{ if(access(*argv, F_OK) != 0 || lstat(*argv, &buf) == -1) 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) for(i = 0; ops[i] != '\0'; ++i)
if(ops[i] == 'e') if(ops[i] == 'e')
@ -97,8 +100,8 @@ usage: fprintf(stderr, "Usage: %s (-%s) [file...]\n",
&& !S_ISLNK(buf.st_mode)) && !S_ISLNK(buf.st_mode))
|| (ops[i] == 'S' || (ops[i] == 'S'
&& !S_ISSOCK(buf.st_mode))) && !S_ISSOCK(buf.st_mode)))
return 1; return EXIT_FAILURE;
}while(*++argv != NULL); }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);
});
}