NAME

OptArgs2::StatusLine - terminal status line

VERSION

v2.0.15 (2025-04-25)

SYNOPSIS

use OptArgs2::StatusLine '$status', 'RS', 'WARN';
use Time::HiRes 'sleep';    # just for simulating work

$status = 'starting ... '; sleep .7;
$status = WARN. 'Warning!';

$status = 'working: ';
foreach my $i ( 1 .. 10 ) {
    $status .= " $i"; sleep .15;
}

# You can localize $status for temporary changes
{
    local $status = 'temporary: '. RS;
    foreach my $i ( 1 .. 10 ) {
        $status = $i; sleep .15;
    }
    sleep 1;
}
$status .= ' (previous)';
sleep 1;

# Right back where you started
$status = "Done.\n";

DESCRIPTION

OptArgs2::StatusLine provides a simple terminal status line implementation, using the perltie mechanism. Simply assigning to a $scalar prints the string to the terminal. The terminal line will be overwritten by the next assignment unless it ends with a newline.

You can create a $status scalar at import time as shown in the SYNOPSIS, or you can tie your own variable manually, even in a HASH:

my $self = bless {}, 'My::Class';
tie $self->{status}, 'OptArgs2::StatusLine';
$self->{status} = 'my status line';

Status variables have a default prefix of "program-name: ". You can change that two ways:

• Use an ASCII record separator (i.e. chr(30)) which you can import as RS, as a prefix / message divider:

  use OptArgs2::StatusLine '$status', 'RS';
  
  $status = 'msg1';                  # "program: my status"
  $status = 'Other: ' . RS . 'msg2'; # "Other: msg2"
  $status = 'msg3';                  # "Other: msg3"

• Assign a scalar reference:

  $status = \'New Prefix: ';
  $status = 'fine';             # "New Prefix: fine"

You can import multiple status variables in one statement:

use OptArgs2::StatusLine '$status', '$d_status';

if ($DEBUG) {
    $d_status = 'debug: '. RS;
} else {
    untie $d_status;
}

$status   = 'frobnicating';     # program: frobnicating
$d_status = 'details matter!';  # debug: details matter!

A status line can be sent to STDERR via warn by prefixing a message with the ASCII enquiry character (i.e. chr(5)) which you can import as WARN:

use OptArgs2::StatusLine '$status', 'WARN';

$status = 'Normal';           # program: normal
$status = WARN . 'Warning!';  # program: Warning! > /dev/stderr

A newline is automatically added to the end of a WARN status. The formatting of the warning is determined by $OptArgs2::StatusLine::WARN_FMT. This is set to "\e[38;5;220m%s\e[0m\n" by default, colouring the text yellow. Set it to a plain "%s" to remove formatting.

SEE ALSO

OptArgs2

SUPPORT & DEVELOPMENT

This distribution is managed via github:

https://github.com/mlawren/p5-OptArgs2

This distribution follows the semantic versioning model:

http://semver.org/

Code is tidied up on Git commit using githook-perltidy:

http://github.com/mlawren/githook-perltidy

AUTHOR

Mark Lawrence <mark@rekudos.net>

LICENSE

Copyright 2022-2025 Mark Lawrence <mark@rekudos.net>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

cpanm OptArgs2

perl -MCPAN -e shell
install OptArgs2