Term::...:Simple(3pm)

💖 Term::ProgressBar::Simple 💖

okay so bestie, welcome to Term::ProgressBar::Simple — the Perl module that lives in the User Contributed Perl Documentation and makes progress bars actually, genuinely, not-annoying. it's giving "simpler progress bars" and honestly? it ate.

---

✨ SYNOPSIS ✨

like, imagine you have stuff to loop over. here's the whole vibe:

# create some things to loop over
my @things = (...);
my $number_of_things = scalar @things;

# create the progress bar object
my $progress = Term::ProgressBar::Simple->new( $number_of_things );

# loop
foreach my $thing (@things) {

    # do some work
    $thing->do_something();

    # increment the progress bar object to tell it a step has been taken.
    $progress++;
}

# See also use of '$progress += $number' later in pod

that's it. that's the whole thing. also peep the $progress += $number usage later down in the pod, iykyk 👑

---

🌸 DESCRIPTION 🌸

progress bars are handy fr fr — they tell you how much work has been done, how much is left to do, and they estimate how long it's gonna take. main character energy for your terminal.

but bestie… they can be fiddly! 😭

this module does the right thing in almost all cases, in a really convenient way. no cap.

---

🦋 FEATURES 🦋

lots! it does all the best practice, periodt:

• wraps Term::ProgressBar::Quiet so there is no output unless the code is running interactively — which means you can put them in cron scripts, slay.
• deals with minor updates — it only refreshes the screen when it will actually change what the user sees, so it's efficient. the way that it doesn't waste your cycles 💅
• completes the progress bar when the progress object is destroyed (explicitly, or by going out of scope) — no more '99%' done. iconic behaviour honestly.

---

🎀 METHODS 🎀

new

# Either...
my $progress = Term::ProgressBar::Simple->new($count);

# ... or
my $progress = Term::ProgressBar::Simple->new(
    {
        count => $count,               #
        name  => 'descriptive text',
    }
);

creates a new progress bar, bestie. you can either just pass in the number of things to do, or hand it a config hash. want the deets? go see Term::ProgressBar. 🫶

increment ( ++ )

$progress++;

incrementing the object makes the progress display update itself. and it's smart about checking whether the display actually needs updating — lowkey a genius move.

increment ( += )

$progress += $number_done;

sometimes you've done more than one step between updates, and that's totally fine. a great example is processing logfiles, where the time taken is relative to the size of the file. in that case, code like this gives you a way better feel for the progress made:

# Get the total size of all the files
my $total_size = sum map { -s } @filenames;

# Set up object with total size as steps to do
my $progress = Term::ProgressBar::Simple->new($total_size);

# process each file and increment by the size of each file
foreach my $filename (@filenames) {
    process_the_file($filename);
    $progress += -s $filename;
}

message

$progress->message('Copying $filename');

outputs a message. it's very much like print, but we try not to disturb the terminal. polite king behaviour 💜

---

👀 SEE ALSO 👀

Term::ProgressBar & Term::ProgressBar::Quiet — go read those too, they're the whole foundation.

---

💀 GOTCHAS 💀

not all operators are overloaded, so things might blow up in interesting ways. patches welcome!! 🙈

---

🌈 THANKS 🌈

• Martyn J. Pearce for the original and great Term::ProgressBar.
• Leon Brocard for doing the hard work in Term::ProgressBar::Quiet, and for submitting a patch with the code for +=.
• YAPC::EU::2008 for providing the venue and coffee whilst the first version of this module was written. ☕

---

👑 AUTHOR 👑

Edmund von der Burg "<evdb@ecclestoad.co.uk>".

<http://www.ecclestoad.co.uk/>

---

🍓 BUGS 🍓

there are no tests — there should be. the smart way would be to trap the output and check it is right. (bestie if you're looking for a side quest… this is it 🧚)

---

⭐ LICENCE AND COPYRIGHT ⭐

Copyright (c) 2008, Edmund von der Burg "<evdb@ecclestoad.co.uk>". All rights reserved.

this module 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 — Term::ProgressBar::Simple, perl v5.34.0, dated 2022-06-17, straight outta the User Contributed Perl Documentation. go forth and make pretty bars. mwah 💅✨