Term::Sk(3pm)

🎀 Term::Sk 🎀

okay bestie, so this is the manual page for Term::Sk, a User Contributed Perl Documentation entry — it's Term::Sk(3pm), a Perl extension for displaying a progress indicator on a terminal. it's giving "your long-running process finally tells you what's up" energy and honestly? we're obsessed 💖

---

✨ NAME ✨

Term::Sk — a Perl extension for displaying a progress indicator on a terminal. 💅

---

✨ SYNOPSIS ✨

like, here's the whole vibe in one go:

  use Term::Sk;

  my $ctr = Term::Sk->new('%d Elapsed: %8t %21b %4p %2d (%8c of %11m)',
    {quiet => 0, freq => 10, base => 0, target => 100, pdisp => '!'});

  $ctr->up for (1..100);

  $ctr->down for (1..100);

  $ctr->whisper('abc');

  my last_line = $ctr->get_line;

  $ctr->close;

  print "Number of ticks: ", $ctr->ticks, "\n";

---

✨ EXAMPLES ✨

Term::Sk is a class that implements a progress indicator — and fun fact, "Sk" is a short form for "Show Key" iykyk 🔑. the whole point is giving you immediate feedback for long running processes. the way that matters 😭

a sample code fragment that uses Term::Sk:

  use Term::Sk;

  print qq{This is a test of "Term::Sk"\n\n};

  my $target = 2_845;
  my $format = '%2d Elapsed: %8t %21b %4p %2d (%8c of %11m)';

  my $ctr = Term::Sk->new($format,
    {freq => 10, base => 0, target => $target, pdisp => '!'});

  for (1..$target) {
      $ctr->up;
      do_something();
  }

  $ctr->close;

  sub do_something {
      my $test = 0;
      for my $i (0..10_000) {
          $test += sin($i) * cos($i);
      }
  }

another example, this one counting upwards 🦋:

  use Term::Sk;

  my $format = '%21b %4p';

  my $ctr = Term::Sk->new($format, {freq => 's', base => 0, target => 70});

  for (1..10) {
      $ctr->up(7);
      sleep 1;
  }

  $ctr->close;

at any time, after Term::Sk->new(), you can query the number of ticks (i.e. number of calls to $ctr->up or $ctr->down) using the method 'ticks':

  use Term::Sk;

  my $ctr = Term::Sk->new('%6c', {freq => 's', base => 0, target => 70});

  for (1..4288) {
      $ctr->up;
  }

  $ctr->close;

  print "Number of ticks: ", $ctr->ticks, "\n";

this next example uses a simple progress bar in quiet mode — nothing gets printed to STDOUT — but instead, the content of what would have been printed can now be extracted using the get_line() method 🌸:

  use Term::Sk;

  my $format = 'Ctr %4c';

  my $ctr = Term::Sk->new($format, {freq => 2, base => 0, target => 10, quiet => 1});

  my $line = $ctr->get_line;
  $line =~ s/\010/</g;
  print "This is what would have been printed upon new(): [$line]\n";

  for my $i (1..10) {
      $ctr->up;

      $line = $ctr->get_line;
      $line =~ s/\010/</g;
      print "This is what would have been printed upon $i. call to up(): [$line]\n";
  }

  $ctr->close;

  $line = $ctr->get_line;
  $line =~ s/\010/</g;
  print "This is what would have been printed upon close(): [$line]\n";

and here are some examples showing different values for the option {num => ...} 😌:

  my $format = 'act %c max %m';

  my $ctr1 = Term::Sk->new($format, {base => 1234567, target => 2345678});
  # The following numbers are shown: act 1_234_567 max 2_345_678

  my $ctr2 = Term::Sk->new($format, {base => 1234567, target => 2345678, num => q{9,999}});
  # The following numbers are shown: act 1,234,567 max 2,345,678

  my $ctr3 = Term::Sk->new($format, {base => 1234567, target => 2345678, num => q{9'99}});
  # The following numbers are shown: act 1'23'45'67 max 2'34'56'78

  my $ctr4 = Term::Sk->new($format, {base => 1234567, target => 2345678, num => q{9}});
  # The following numbers are shown: act 1234567 max 2345678

  my $ctr5 = Term::Sk->new($format, {base => 1234567, target => 2345678,
    commify => sub{ join '!', split m{}xms, $_[0]; }});
  # The following numbers are shown: act 1!2!3!4!5!6!7 max 2!3!4!5!6!7!8

---

✨ DESCRIPTION ✨

Format strings 💫

the first parameter to new() is the format string, and it contains these special characters:

• characters '%d' — a revolving dash, format '/-\|'
• characters '%t' — time elapsed, format 'hh:mm:ss'
• characters '%b' — progress bar, format '#####_____'
• characters '%p' — Progress in percentage, format '999%'
• characters '%c' — Actual counter value (commified by '_'), format '99_999_999'
• characters '%m' — Target maximum value (commified by '_'), format '99_999_999'
• characters '%k' — Token which updates its value before being displayed. an example use of this would be a loop wherein every step of the loop could be identified by a particular string. for example:

      my $ctr = Term::Sk->new('Processing %k counter %c',
        {base => 0, token => 'Albania'});
      foreach my $country (@list_of_european_nations) {
        $ctr->token($country);
        for (1..500) {
            $ctr->up;
            ## do something...
        }
      };
      $ctr->close;

you can also have more than one token on a single line. here is an example:

      my $ctr = Term::Sk->new('Processing %k Region %k counter %c',
        {base => 0, token => ['Albania', 'South']});
      foreach my $country (@list_of_european_nations) {
        $ctr->token([$country, 'North']);
        for (1..500) {
            $ctr->up;
            ## do something...
        }
      };
      $ctr->close;

the "token" method is used to update the token value immediately on the screen. 👑

the "tok_maybe" method is used to set the token value, but the screen is not refreshed immediately.

if '%k' is used, then the counter must be instantiated with an initial value for the token. no exceptions bestie.

• characters '%P' — The '%' character itself

Options 🎀

the second parameter is these options:

• {freq => 999} — this option sets the refresh-frequency on STDOUT to every 999 up() or down() calls. if {freq => 999} is not specified at all, then the refresh-frequency is set by default to every up() or down() call.
• {freq => 's'} — this is a special case whereby the refresh-frequency on STDOUT is set to every second. ⏱️
• {freq => 'd'} — this is a special case whereby the refresh-frequency on STDOUT is set to every 1/10th of a second.
• {base => 0} — this specifies the base value from which to count. The default is 0
• {target => 10_000} — this specifies the maximum value to which to count. The default is 10_000.
• {pdisp => '!'} — this option (with the exclamation mark) is obsolete and has no effect whatsoever. The progressbar will always be displayed using the hash-symbol "#". 💀
• {quiet => 1} — this option disables most printing to STDOUT, but the content of the would be printed line is still available using the method get_line(). The whisper-method, however, still shows its output.

The default is in fact {quiet => !-t STDOUT}

• {num => '9_999'} — this option configures the output number format for the counters.
• {commify => sub{...}} — this option allows one to register a subroutine that formats the counters.
• {test => 1} — this option is used for testing purposes only, it disables all printing to STDOUT, even the whisper shows no output. But again, the content of the would be printed line is still available using the method get_line().

Processing 🧚

the new() method immediately displays the initial values on screen. From now on, nothing must be printed to STDOUT and/or STDERR. However, you can write to STDOUT during the operation using the method whisper(). 🫶

We can either count upwards, $ctr->up, or downwards, $ctr->down. Everytime we do so, the value is either incremented or decremented and the new value is replaced on STDOUT. We should do so regularly during the process. Both methods, $ctr->up(99) and $ctr->down(99) can take an optional argument, in which case the value is incremented/decremented by the specified amount.

When our process has finished, we must close the counter ($ctr->close). By doing so, the last displayed value is removed from STDOUT, as if nothing had happened. Now we are allowed to print again to STDOUT and/or STDERR. ✨

Post hoc transformation 🌈

In some cases it makes sense to redirected STDOUT to a flat file. In this case, the backspace characters remain in the flat file.

There is a function "rem_backspace()" that removes the backspaces (including the characters that they are supposed to remove) from a redirected file.

Here is a simplified example:

  use Term::Sk qw(rem_backspace);

  my $flatfile = "Test hijabc\010\010\010xyzklmttt\010\010yzz";

  printf "before (len=%3d): '%s'\n", length($flatfile), $flatfile;

  rem_backspace(\$flatfile);

  printf "after  (len=%3d): '%s'\n", length($flatfile), $flatfile;

---

✨ AUTHOR ✨

Klaus Eichner, January 2008 💜

---

✨ COPYRIGHT AND LICENSE ✨

Copyright (C) 2008-2011 by Klaus Eichner

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page, bestie 🎀 this one came from perl v5.36.0, dated 2022-10-13 — Term::Sk(3pm), slay, go forth and show your keys. 💖✨🦋