diff --git a/CONDUCT b/CONDUCT new file mode 100644 index 0000000..4dd97a9 --- /dev/null +++ b/CONDUCT @@ -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] +[1] diff --git a/CONTRIBUTING b/CONTRIBUTING index d7fdc8e..74e821e 100644 --- a/CONTRIBUTING +++ b/CONTRIBUTING @@ -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 diff --git a/Makefile b/Makefile index 734a62c..2188b41 100644 --- a/Makefile +++ b/Makefile @@ -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 \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 diff --git a/README b/README index accfc7e..68be16c 100644 --- a/README +++ b/README @@ -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 diff --git a/docs/dj.1 b/docs/dj.1 index 1e286f5..7d28ac8 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -1,14 +1,13 @@ .\" Copyright (c) 2024 DTB +.\" Copyright (c) 2024 Emma Tebibyte .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - -.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= ibs=1024 skip=0 align=ff count=0 +out= 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 . - +.\" .SH SEE ALSO - -dd(1) +.BR dd (1p) diff --git a/docs/false.1 b/docs/false.1 index 6883802..5b582dd 100644 --- a/docs/false.1 +++ b/docs/false.1 @@ -1,35 +1,35 @@ .\" Copyright (c) 2022, 2024 DTB -.\" Copyright (c) 2023 Emma Tebibyte +.\" Copyright (c) 2023–2024 Emma Tebibyte .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - -.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 . - +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 . - +.\" .SH SEE ALSO - -true(1p) +.BR true (1p) diff --git a/docs/fop.1 b/docs/fop.1 new file mode 100644 index 0000000..f7afa54 --- /dev/null +++ b/docs/fop.1 @@ -0,0 +1,62 @@ +.\" Copyright (c) 2024 DTB +.\" Copyright (c) 2024 Emma Tebibyte +.\" +.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, +.\" visit . +.\" +.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 +. +.\" +.SH SEE ALSO +.BR sed (1p) diff --git a/docs/hru.1 b/docs/hru.1 index c75cb73..346f200 100644 --- a/docs/hru.1 +++ b/docs/hru.1 @@ -2,56 +2,68 @@ .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - -.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 . - +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 . - +.\" .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 diff --git a/docs/intcmp.1 b/docs/intcmp.1 index f370755..315cda2 100644 --- a/docs/intcmp.1 +++ b/docs/intcmp.1 @@ -1,78 +1,105 @@ .\" Copyright (c) 2023–2024 DTB -.\" Copyright (c) 2023 Emma Tebibyte +.\" Copyright (c) 2023–2024 Emma Tebibyte .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - -.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 . - +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 . - +.\" .SH SEE ALSO - -strcmp(1), scrut(1), str(1), test(1p) +.BR scrut (1), +.BR strcmp (1), +.BR str (1), +.BR test (1p) diff --git a/docs/mm.1 b/docs/mm.1 index 2244588..3ca0722 100644 --- a/docs/mm.1 +++ b/docs/mm.1 @@ -2,13 +2,11 @@ .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - -.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 . - +.\" .SH SEE ALSO - -cat(1p), dd(1), dj(1), tee(1p) +.BR cat (1p), +.BR dd (1), +.BR dj (1), +.BR tee (1p) diff --git a/docs/npc.1 b/docs/npc.1 index 7f66c3d..51cb851 100644 --- a/docs/npc.1 +++ b/docs/npc.1 @@ -1,68 +1,74 @@ .\" Copyright (c) 2023–2024 DTB -.\" Copyright (c) 2023 Emma Tebibyte +.\" Copyright (c) 2023–2024 Emma Tebibyte .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - -.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 . - +Written by DTB +.MT trinity@trinity.moe +.ME . +.\" .SH COPYRIGHT Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later . - +.\" .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 diff --git a/docs/rpn.1 b/docs/rpn.1 index 2197fbe..7d3b477 100644 --- a/docs/rpn.1 +++ b/docs/rpn.1 @@ -3,68 +3,84 @@ .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - -.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 . - +Written by Emma Tebibyte +.MT emma@tebibyte.media +.ME . +.\" .SH COPYRIGHT Copyright (c) 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later . - +.\" .SH SEE ALSO - -bc(1p), dc(1), rpn(7), IEEE 754 +.BR bc (1p), +.BR dc (1), +.BR rpn (7), +.I IEEE 754 diff --git a/docs/scrut.1 b/docs/scrut.1 index 7a5107a..1e17f7e 100644 --- a/docs/scrut.1 +++ b/docs/scrut.1 @@ -1,93 +1,86 @@ .\" Copyright (c) 2024 DTB +.\" Copyright (c) 2024 Emma Tebibyte .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - -.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 . - +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 . - +.\" .SH SEE ALSO - -access(3p), lstat(3p), test(1p) +.BR access (3p), +.BR lstat (3p), +.BR test (1p) diff --git a/docs/str.1 b/docs/str.1 index ecf71ee..6f01125 100644 --- a/docs/str.1 +++ b/docs/str.1 @@ -1,58 +1,60 @@ .\" Copyright (c) 2023–2024 DTB -.\" Copyright (c) 2023 Emma Tebibyte +.\" Copyright (c) 2023–2024 Emma Tebibyte .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - -.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 . - +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 . - +.\" .SH SEE ALSO - -ctype(3p), strcmp(1), ascii(7) +.BR ctype (3p), +.BR strcmp(1), +.BR ascii(7) diff --git a/docs/strcmp.1 b/docs/strcmp.1 index 14c0d0d..2ff08f6 100644 --- a/docs/strcmp.1 +++ b/docs/strcmp.1 @@ -1,62 +1,76 @@ .\" Copyright (c) 2023–2024 DTB -.\" Copyright (c) 2023 Emma Tebibyte +.\" Copyright (c) 2023–2024 Emma Tebibyte .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - -.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 . - +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 . - +.\" .SH SEE ALSO - -strcmp(3), intcmp(1), scrut(1), test(1p) +.BR strcmp (3), +.BR intcmp (1), +.BR scrut (1), +.BR test (1p) diff --git a/docs/swab.1 b/docs/swab.1 index a0c1be3..1c75705 100644 --- a/docs/swab.1 +++ b/docs/swab.1 @@ -1,14 +1,13 @@ .\" Copyright (c) 2024 DTB +.\" Copyright (c) 2024 Emma Tebibyte .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - -.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 . - +.\" .SH SEE ALSO - -dd(1p) +.BR dd (1p) diff --git a/docs/true.1 b/docs/true.1 index 3c292d8..ebf8916 100644 --- a/docs/true.1 +++ b/docs/true.1 @@ -1,35 +1,36 @@ .\" Copyright (c) 2022, 2024 DTB -.\" Copyright (c) 2023 Emma Tebibyte +.\" Copyright (c) 2023–2024 Emma Tebibyte .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - -.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 . - +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 . - +.\" .SH SEE ALSO - -false(1p) +.BR false (1p), +.BR true (1p) diff --git a/src/fop.rs b/src/fop.rs index e0bba4c..29f1522 100644 --- a/src/fop.rs +++ b/src/fop.rs @@ -32,12 +32,13 @@ use sysexits::{ EX_DATAERR, EX_IOERR, EX_UNAVAILABLE, EX_USAGE }; fn main() { let argv = args().collect::>(); - 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::>(); + let mut fields = buf.split(&d).collect::>(); let opts = argv .iter() diff --git a/src/mm.c b/src/mm.c index ff62148..dc337b7 100644 --- a/src/mm.c +++ b/src/mm.c @@ -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; diff --git a/src/scrut.c b/src/scrut.c index e2494d3..c5b675f 100644 --- a/src/scrut.c +++ b/src/scrut.c @@ -1,5 +1,6 @@ /* - * Copyright (c) 2023 DTB + * Copyright (c) 2023–2024 DTB + * Copyright (c) 2024 Emma Tebibyte * 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 /* fprintf(3), stderr, NULL */ -#include /* EXIT_FAILURE */ +#include /* EXIT_FAILURE, EXIT_SUCCESS */ #include /* memset(3), strchr(3) */ +#ifndef EX_USAGE +# include +#endif #include /* access(3), getopt(3), F_OK, R_OK, W_OK, X_OK */ #include /* 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 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; } diff --git a/src/test.rs b/src/test.rs deleted file mode 100644 index 4a602b1..0000000 --- a/src/test.rs +++ /dev/null @@ -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); - }); -}