NAME
    Progress::Any::Output::TermProgressBarColor - Output progress to
    terminal as color bar

VERSION
    This document describes version 0.249 of
    Progress::Any::Output::TermProgressBarColor (from Perl distribution
    Progress-Any-Output-TermProgressBarColor), released on 2020-08-15.

SYNOPSIS
     use Progress::Any::Output;

     # use default options
     Progress::Any::Output->set('TermProgressBarColor');

     # set options
     Progress::Any::Output->set('TermProgressBarColor',
                                width=>50, fh=>\*STDERR, show_delay=>5);

DESCRIPTION
    THIS IS AN EARLY RELEASE, SOME THINGS ARE NOT YET IMPLEMENTED E.G.
    STYLES, COLOR THEMES.

    Sample screenshots:

    This output displays progress indicators as colored progress bar on
    terminal. It produces output similar to that produced by
    Term::ProgressBar, except that it uses the Progress::Any framework and
    has additional features:

    *   colors and color themes

    *   template and styles

    *   displaying message text in addition to bar/percentage number

    *   wide character support

    XXX option to cleanup when complete or not (like in Term::ProgressBar)
    and should default to 1.

METHODS
  new(%args) => OBJ
    Instantiate. Usually called through
    "Progress::Any::Output->set("TermProgressBarColor", %args)".

    Known arguments:

    *   freq => num

        Limit the frequency of output updating. 0 means no frequency
        limiting (update output after every "update()").

        A positive number means to update output when there has been that
        amount of difference in position since last "update()". For example,
        if "freq" is 10 and the last "update()" was at position 5, then the
        next output update will be when position is at least 15.

        A negative number means to update output when time has passed that
        amount of absolute value (in seconds). For example, if "freq" is -3
        and the last "update()" was 1 second ago, then the next output
        update will not be until the next two seconds has passed.

        By default undef, in which case Progress::Any will use the default
        -0.5 (at most once every 0.5 seconds).

    *   wide => bool

        If set to 1, enable wide character support (requires
        Text::ANSI::WideUtil.

    *   width => INT

        Width of progress bar. The default is to detect terminal width and
        use the whole width.

    *   color_theme => STR

        Not yet implemented.

        Choose color theme. To see what color themes are available, use
        "list_color_themes()".

    *   style => STR

        Not yet implemented.

        Choose style. To see what styles are available, use "list_styles()".
        Styles determine the characters used for drawing the bar, alignment,
        etc.

    *   template => str

        See fill_template in Progress::Any's documentation. Aside from
        conversions supported by Progress::Any, this output recognizes these
        additional conversions: %b to display the progress bar (with width
        using the rest of the available width), %B to display the progress
        bar as well as the message inside it. You can also enclose parts of
        text with "<color RGB>" ... "</color>" to give color.

        The default template is:

         <color ffff00>%p</color> <color 808000>[</color>%B<color 808000>]</color><color ffff00>%e</color>

    *   fh => handle (default: \*STDERR)

        Instead of the default STDERR, you can direct the output to another
        filehandle e.g. STDOUT.

    *   show_delay => int

        If set, will delay showing the progress bar until the specified
        number of seconds. This can be used to create, e.g. a CLI
        application that is relatively not chatty but will display progress
        after several seconds of seeming inactivity to indicate users that
        the process is still going on.

    *   rownum => uint

        Default 0. Can be set to put the progress bar at certain rownum.
        This can be used to display several progress bars together.

  keep_delay_showing()
    Can be called to reset the timer that counts down to show progress bar
    when "show_delay" is defined. For example, if "show_delay" is 5 seconds
    and two seconds have passed, it should've been 3 seconds before progress
    bar is shown in the next "update()". However, if you call this method,
    it will be 5 seconds again before showing.

FAQ
  How to update progress bar output more often?
    Set "freq" to e.g. -0.1 or -0.05. The default "freq", when unset, is
    -0.5 which means to update output at most once every 0.5 second.

  How to display a different message for this output?
    For example, this output formats message using String::Elide::Parts so
    inside the message, substrings can be tagged for eliding priority:

     <elspan prio=2>Downloading </elspan><elspan prio=3 truncate=middle>http://127.0.0.1:7007/2.mp4 </elspan>37.3M/139.5M

    while another output like Progress::Any::Output::TermMessage does not
    use String::Elide::Parts. It should just display the string as:

     Downloading http://127.0.0.1:7007/2.mp4 37.3M/139.5M

    In the indicator, you can provide a specific message for this output:

     $progress->update(
         message => 'Downloading http://127.0.0.1:7007/2.mp4 37.3M/139.5M',
         'message.alt.output.TermProgressBarColor' => '<elspan prio=2>Downloading </elspan><elspan prio=3 truncate=middle>http://127.0.0.1:7007/2.mp4 </elspan>37.3M/139.5M',
         ...
     );

ENVIRONMENT
  NO_COLOR
    Bool. Can be used to disable color. Consulted before NO_COLOR. See
    Color::ANSI::Util.

  COLOR
    Bool. Can be used to force or disable color. See Color::ANSI::Util.

  COLOR_DEPTH
    Integer. Can be used to override color depth detection. See
    Color::ANSI::Util.

  COLUMNS
    Integer. Can be used to override terminal width detection.

  PROGRESS_TERM_BAR
    Bool. Forces disabling or enabling progress output (just for this
    output).

    In the absence of PROGRESS_TERM_MESSAGE and PROGRESS, will default to 1
    if filehandle is detected as interactive (using "-t").

  PROGRESS
    Bool. Forces disabling or enabling progress output (for all outputs).

HOMEPAGE
    Please visit the project's homepage at
    <https://metacpan.org/release/Progress-Any-Output-TermProgressBarColor>.

SOURCE
    Source repository is at
    <https://github.com/perlancar/perl-Progress-Any-Output-TermProgressBarCo
    lor>.

BUGS
    Please report any bugs or feature requests on the bugtracker website
    <https://rt.cpan.org/Public/Dist/Display.html?Name=Progress-Any-Output-T
    ermProgressBarColor>

    When submitting a bug or request, please include a test-file or a patch
    to an existing test-file that illustrates the bug or desired feature.

SEE ALSO
    Progress::Any

    Term::ProgressBar

    Ruby library: ruby-progressbar,
    <https://github.com/jfelchner/ruby-progressbar>

AUTHOR
    perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2020, 2018, 2017, 2016, 2015, 2014, 2013
    by perlancar@cpan.org.

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

