bonsai/harakit
5
4
Fork 3
Code Issues 42 Pull Requests 3 Projects 1 Releases 36 Activity

Merge branch 'main' into peek

Browse Source
This commit is contained in:
dtb
2024-07-27 18:46:48 -06:00
parent 3f23e437e8 e90d25e30f
commit a217c4f631
30 changed files with 938 additions and 1818 deletions
Download Patch File Download Diff File Expand all files Collapse all files

165
docs/dj.1
View File

@@ -4,32 +4,24 @@
.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
.\"
.TH DJ 1 2024-06-17 "Harakit X.X.X"
.TH DJ 1 2024-07-03 "Harakit X.X.X"
.SH NAME
dj \(en disk jockey
.\"
.SH SYNOPSIS
dj
.RB ( -AdHnq )
.RB ( -a
.RB [ byte ])
.RB ( -c
.RB [ count ])
.RB [ -Hn ]
.RB [ -a\ byte ]
.RB [ -c\ count ]
.RB ( -i
[\fBinput file\fP])
.RB ( -b
[\fBinput block size\fP])
.RB ( -s
[\fBinput offset\fP])
.RB [ -i\ file ]
.RB [ -b\ block_size ]
.RB [ -s\ offset ]
.RB ( -o
[\fBoutput file\fP])
.RB ( -B
[\fBoutput block size\fP])
.RB ( -S
[\fBoutput offset\fP])
.RB [ -o\ file ]
.RB [ -B\ block_size ]
.RB [ -S\ offset ]
.\"
.SH DESCRIPTION
@@ -42,68 +34,109 @@ 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.
The offset used when skipping or seeking refers to how many bytes are skipped
or sought. Running
.BR dj (1)
with a skip offset of 1 skips one byte into the input and reads from the second
byte onwards. A programmer may think of a file as a zero-indexed array of
bytes; in this analogy, the offset given is the index of the byte at which to
start reading or writing.
.\"
.SH OPTIONS
.IP \fB-i\fP
.IP \fB-i\fP\ \fIfile\fP
Takes a file path as an argument and opens it for use as an input.
.IP \fB-b\fP
.IP \fB-b\fP\ \fIblock_size\fP
Takes a numeric argument as the size in bytes of the input buffer, the default
being 1024.
.IP \fB-s\fP
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.
Takes a numeric argument as the index of the byte at which reading will
commence; \(lqskips\(rq that number of bytes. 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
.IP \fB-B\fP\ \fIblock_size\fP
Does the same as
.B -b
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.
Takes a numeric argument as the index of the byte at which writing will
commence; \(lqseeks\(rq that number of bytes. If the standard output is used,
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
with a null byte instead of a character.
of an incomplete read from the input file. If the option argument is empty, the
null byte is used.
.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
Prints diagnostic 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.
input file 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.
the output file is \(lq-\(rq.
.\"
.SH EXAMPLES
The following
.BR sh (1p)
line:
.RS
printf 'Hello, world!\(rsn' | dj -c 1 -b 7 -s 7 2>/dev/null
.RE
Produces the following output:
.RS
world!
.RE
The following
.BR sh (1p)
lines run sequentially:
.RS
tr '\(rs0' 0 </dev/zero | dj -c 1 -b 6 -o hello.txt
tr '\(rs0' H </dev/zero | dj -c 1 -b 1 -o hello.txt
tr '\(rs0' e </dev/zero | dj -c 1 -b 1 -o hello.txt -S 1
tr '\(rs0' l </dev/zero | dj -c 1 -b 2 -o hello.txt -S 2
tr '\(rs0' o </dev/zero | dj -c 1 -b 1 -o hello.txt -S 4
tr '\(rs0' '\(rsn' </dev/zero | dj -c 1 -b 1 -o hello.txt -S 5
dj -i hello.txt
.RE
Produce the following output:
.RS
Hello
.RE
It may be particularly illuminating to print the contents of the example
.B hello.txt
after each
.BR dj (1)
invocation.
.\"
.SH DIAGNOSTICS
On a partial or empty read, unless the
.B -q
option is specified, a diagnostic message is printed. Then, the program exits
unless the
On a partial or empty read, a diagnostic message is printed. Then, the program
exits unless the
.B -n
option is specified.
@@ -128,20 +161,6 @@ option may be specified. In this event, the following format is used instead:
{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)
@@ -156,17 +175,26 @@ is specified along with the
option and a count, actual byte output is the product of the count and the input
block size and therefore may be lower than expected. If the
.B -a
or
.B -A
options are specified, this could make written data nonsensical.
option is 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.
The options
.B -b
and
.B -B
could be confused for each other, and so could
.B -s
and
.BR -S .
The lowercase option affects input and the capitalized option affects output.
The skipped or sought bytes while processing irregular files, such as streams,
are reported in the diagnostic output, because they were actually read or
written. This is as opposed to bytes skipped while processing regular files,
which are not reported.
.\"
.SH RATIONALE
@@ -187,3 +215,4 @@ Copyright \(co 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
.\"
.SH SEE ALSO
.BR dd (1p)
.BR lseek (3p)

2
docs/fop.1
View File

@@ -22,7 +22,7 @@ Performs operations on specified fields in data read from the standard input.
.\"
.SH OPTIONS
.IP \fB-d\fP
.IP \fB-d\fP\ \fIdelimiter\fP
Sets a delimiter by which the input data will be split into fields. The default
is an ASCII record separator.
.\"

4
docs/intcmp.1
View File

@@ -11,9 +11,7 @@ intcmp \(en compare integers
.SH SYNOPSIS
intcmp
.RB ( -egl )
.RB [ integer ]
.RB [ integer... ]
.RB [ -egl ]\ integer\ integer...
.SH DESCRIPTION
Compare integers to each other.
.\"

38
docs/mm.1
View File

@@ -3,18 +3,16 @@
.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
.\"
.TH MM 1 2024-06-17 "Harakit X.X.X"
.TH MM 1 2024-07-14 "Harakit X.X.X"
.SH NAME
mm \(en middleman
.\"
.SH SYNOPSIS
mm
.RB ( -aenu )
.RB ( -i
.RB [ input ])
.RB ( -o
.RB [ output ])
.RB [ -aetu ]
.RB [ -i\ input ]
.RB [ -o\ output ]
.\"
.SH DESCRIPTION
@@ -23,19 +21,25 @@ Catenate input files and write them to the start of each output file or stream.
.SH OPTIONS
.IP \fB-a\fP
Opens subsequent outputs for appending rather than updating.
Opens 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-t\fP
Causes outputs to be overwritten instead of being truncated.
.IP \fB-u\fP
Ensures neither input or output will be buffered.
.IP \fB-n\fP
Causes SIGINT signals to be ignored.
.IP \fB-i\fP\ \fIinput\fP
Opens a path as an input. If one or more of the input files is \(lq-\(rq or if
no inputs are specified, the standard input shall be used. If specified as the
last option and if there are trailing arguments to the program, they shall be
appended to the list of files to use as inputs.
.IP \fB-o\fP\ \fIoutput\fP
Opens a path as an output. If one or more of the output files is \(lq-\(rq or if
no outputs are specified and the
.B -e
option is not specified, the standard output shall be used. If specified as the
last option and if there are trailing arguments to the program, they shall be
appended to the list of files to use as outputs.
.\"
.SH DIAGNOSTICS
@@ -47,10 +51,6 @@ exits with the appropriate
.BR sysexits.h (3)
status.
.\"
.SH CAVEATS
Existing files are not truncated on ouput and are instead overwritten.
.\"
.SH RATIONALE
The

2
docs/npc.1
View File

@@ -11,7 +11,7 @@ npc \(en show non-printing characters
.SH SYNOPSIS
npc
.RB ( -et )
.RB [ -et ]
.\"
.SH DESCRIPTION

4
docs/scrut.1
View File

@@ -10,8 +10,8 @@ scrut \(en scrutinize file properties
.SH SYNOPSIS
scrut
.RB ( -LSbcdefgkprsuwx )
.RB [ file... ]
.RB [ -LSbcdefgkprsuwx ]
.B file...
.\"
.SH DESCRIPTION

3
docs/str.1
View File

@@ -11,8 +11,7 @@ str \(en test string arguments
.SH SYNOPSIS
str
.RB [ type ]
.RB [ string... ]
.B type string...
.\"
.SH DESCRIPTION

13
docs/strcmp.1
View File

@@ -4,15 +4,14 @@
.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
.\"
.TH STRCMP 1 2024-06-17 "Harakit X.X.X"
.TH STRCMP 1 2024-07-15 "Harakit X.X.X"
.SH NAME
strcmp \(en compare strings
.\"
.SH SYNOPSIS
strcmp
.RM [ string ]
.RB [ strings... ]
.B string string...
.\"
.SH DESCRIPTION
@@ -21,15 +20,15 @@ Check whether string arguments are the same.
.SH DIAGNOSTICS
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:
will exit with an error code less than 128 if a string passed has a lesser byte
value than one of the prior strings:
.RS
strcmp b a
.RE
or with an error code of 255 if it has a greater byte value than one of the
prior strings:
or with an error code greater than 128 if it has a greater byte value than one
of the prior strings:
.RS
strcmp a b

17
docs/swab.1
View File

@@ -11,11 +11,7 @@ swab \(en swap bytes
.SH SYNOPSIS
swab
.RB ( -f )
.RB ( -w
.R [
.B word size
.R ])
.RB [ -w\ word_size ]
.\"
.SH DESCRIPTION
@@ -23,13 +19,10 @@ 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.
.IP \fB-w\fP\ \fIword_size\fP
Configures the word size; that is, the size in bytes of the block size on which
to operate. The default word size is 2. The word size must be cleanly divisible
by 2, otherwise the block of bytes being processed can\(cqt be halved.
.\"
.SH EXAMPLES