Modes

Splitby works with two important mode types: an input mode (how to read the data) and a selection mode (what to extract from it).

Input mode: This defines how you want to read the input. Unix tools by default split their input by line, processing each individually. Splitby also offers the ability to process the input as a single string, or to split it by zero-terminators instead.

Selection mode: This tells splitby what you want to select from the input. Typically you’d split text by a delimiter: this is fields mode. But you can also choose to select specific characters, or even specific bytes

Input modes

Per-line (--per-line)

Default

splitby reads one line at a time and applies selections to each line.

printf "a,b\nc,d\n" | splitby -d "," 1
# a
# c

Whole-string (-w, --whole-string)

Treats the entire input as a single record. This is useful when your delimiter is \n or you want to operate across line breaks.

printf "a,b\nc,d\n" | splitby -w -d "\n" 2
# c,d

Zero-terminated (-z, --zero-terminated)

Reads and writes NUL-delimited records. This is useful when piping from tools like find -print0.

printf "name,age\0alice,30\0" | splitby -z -d "," 1
# name
# alice

Selection modes

Fields (-f, --fields)

Splits by a regex delimiter and selects fields. This is the most common mode.

Note: This mode requires a delimiter to function properly, or it won’t know how to split the text.

Characters (-c, --characters)

Selects by visible characters (grapheme clusters).

echo "café" | splitby -c 1-3
# caf

Bytes (-b, --bytes)

Selects raw byte offsets. Useful for binary or fixed-width data.

echo "abc" | splitby -b 1-2
# ab