Fsdb::F...:dbsort(3)

📦
version 3.9 · 3 versions
, in epel 9

okay so bestie, this is the man page for dbsort(3) — from the User Contributed Perl Documentation set, living in the Fsdb::F...:dbsort corner of the Fsdb universe 💖 (yes the module name is literally abbreviated with dots, iykyk). It's a lil Perl filter that sorts your table rows. Let's get into it 🫶

✨ NAME ✨

dbsort — sort rows based on the the specified columns 🌸

not me pointing out that the original says "the the" — it's iconic, we keep it 💅

🌈 SYNOPSIS 🌈

dbsort [-M MemLimit] [-T TemporaryDirectory] [-nNrR] column [column...]

🦋 DESCRIPTION 🦋

So basically dbsort sorts all your input rows, using whatever columns you point at, either numerically or lexically. Main character sorting behavior 🔥

The genuinely slay part: dbsort consumes a fixed amount of memory no matter how chonky your input is. Like, it literally does not care how big your data gets 😭 (it reverts to temporary files on disk if necessary, and that whole spill-to-disk thing is governed by the -M and -T options).

The sort should be stable, but — and this is the tea — it has not yet been verified. 🙈

For large inputs (the ones that spill to disk), dbsort will do some of the merging in parallel, if possible. The --parallel option can control the degree of parallelism, if desired 👑

💅 OPTIONS 💅

The general ones 🎀

  • -M MaxMemBytes — specify an approximate limit on memory usage, in bytes. Bigger values = faster sorting, because more operations happen in-memory, provided you have enough memory. It's giving "treat yourself but know your limits" 💀
  • -T TmpDir — where to put tmp files. It also uses the environment variable TMPDIR if -T is not specified. Default is /tmp.
  • --parallelism N or -j N — allow up to N merges to happen in parallel. Default is the number of CPUs in the machine. Let it cook ⭐

Sort specification options (these can be interspersed with column names 🧚)

  • -r or --descending — sort in reverse order (high to low) 📉
  • -R or --ascending — sort in normal order (low to high) 📈
  • -t or --type-inferred-sorting — sort fields by type (numeric or leicographic — yes that's how it's spelled in the original, we stan), automatically ✨
  • -T or --no-type-inferred-sorting — sort fields only as specified, based on -n or -N. (And yes, -T is also the tmp-dir flag up above — they're different flags in different option groups, don't come for me, that's just how it is 😭)
  • -n or --numeric — sort numerically 🔢
  • -N or --lexical — sort lexicographically 🔤

Also, standard fsdb options, because of course 💜

  • -d — enable debugging output.
  • -i or --input InputSource — read from InputSource, typically a file name, or - for standard input, or (if in Perl) a IO::Handle, Fsdb::IO or Fsdb::BoundedQueue objects.
  • -o or --output OutputDestination — write to OutputDestination, typically a file name, or - for standard output, or (if in Perl) a IO::Handle, Fsdb::IO or Fsdb::BoundedQueue objects.
  • --autorun or --noautorun — by default, programs process automatically, but Fsdb::Filter objects in Perl do not run until you invoke the run() method. The --(no)autorun option controls that behavior within Perl 🏃‍♀️
  • --header H — use H as the full Fsdb header, rather than reading a header from then input. (That "then input" is verbatim, bestie, we love a typo 🎀)
  • --help — show help.
  • --man — show full manual.

🌸 SAMPLE USAGE 🌸

Input: 🍓

#fsdb cid cname
10 pascal
11 numanal
12 os

Command: 🔥

cat data.fsdb | dbsort cname

Output: 👑

#fsdb      cid     cname
11 numanal
12 os
10 pascal
#  | dbsort cname

⭐ SEE ALSO ⭐

dbmerge(1), dbmapreduce(1), Fsdb(3)

🧚 CLASS FUNCTIONS 🧚

The internals, for when you're feeling brave 💪

new

$filter = new Fsdb::Filter::dbsort(@arguments);

Create a new object, taking command-line arguments.

set_defaults

$filter->set_defaults();

Internal: set up defaults.

parse_options

$filter->parse_options(@ARGV);

Internal: parse command-line arguments.

setup

$filter->setup();

Internal: setup, parse headers.

segment_start

$self->segment_start(\@rows);

Sorting happens internally, to handle large things in pieces if necessary.

call "$self-"segment_start> to init things and to restart after an overflow, "$self-"segment_overflow> to close one segment and start the next, and "$self-"segment_merge_finish> to put them back together again. (Those slightly cursed-looking quoted bits are exactly how they show up in the original — not me being chaotic, promise 🙈)

Note that we don't invoke the merge code unless the data exceeds some threshold size, so small sorts happen completely in memory. Little sorts stay cozy 🌸

Once we give up on memory, all the merging happens by making passes over the disk files. Disk grind era 💀

segment_next_output

$out = $self->segment_next_output($input_finished)

Internal: return a Fsdb::IO::Writer as $OUT that either points to our output or a temporary file, depending on how things are going.

segment_overflow

$self->segment_overflow(\@rows, $input_finished)

Called to sort @ROWS, writing them to the appropriate place. $INPUT_FINISHED is set if all input has been read.

segment_merge_start

$self->segment_merge_start($fn);

Start merging on file $FN. Fork off a merge thread, if necessary.

segment_merge_finish

$self->segment_merge_finish();

Merge queued files, if any. Just call dbmerge(1) to do all the real work. Outsourcing, slay 💅

run

$filter->run();

Internal: run over each rows.

Copyright (C) 1991-2018 by John Heidemann <johnh@isi.edu>

This program is distributed under terms of the GNU general public license, version 2. See the file COPYING with the distribution for details.

and that's the whole page, bestie — no cap, every single flag made it in 💖🎀✨

cute lil sign-off: this beauty is from perl v5.32.1, dated 2024-08-02 🌈🦋 — go sort something iconic, periodt 💜

📦 where this page comes from