NAME

    Term::Spinner::Color - A terminal spinner/progress bar with Unicode,
    color, and no non-core dependencies.

SYNOPSIS

        use utf8;
        use 5.010;
        use Term::Spinner::Color;
        my $spin = Term::Spinner::Color->new(
          seq => ['◑', '◒', '◐', '◓'],
          );
        $spin->start();
        $spin->next() for 1 .. 10;
        $spin->done();

    Or, if you want to not worry about ticking the sequence forward with
    next you can use the auto_start and auto_done methods instead.

        use utf8;
        use 5.010;
        use Term::Spinner::Color;
        my $spin = Term::Spinner::Color->new(
          'delay' => 0.3,
          'colorcycle' => 1,
          );
        $spin->auto_start();
        sleep 5; # do something slow here
        $spin->auto_done();

DESCRIPTION

    This is a simple spinner, useful when you want to show some kind of
    activity during a long-running process of indeterminant length. It's
    loosely based on the API from Term::Spinner and Term::Spinner::Lite.
    Unlike Term::Spinner though, this module doesn't have any dependencies
    outside of modules shipped with Perl itself. And, unlike
    Term::Spinner::Lite, this module has color support and support for wide
    progress bars.

    This module also provides an asynchronous mode, which does not require
    your program to manually call the next method.

    Some features and some (Unicode) frame sets do not work in Windows
    PowerShell or cmd.exe. If you must work across a wide variety of
    platforms, choosing ASCII frame sets is wise. run_ok method currently
    only provides Unicode output, so it is not suitable for use on Windows
    (bash, of many types, on Windows works fine, however). There's probably
    a way to fix this by switching to another code page in Windows shells.

ATTRIBUTES

    delay

      If used asynchronously, this is how long each tick will last. It uses
      the Time::HiRes sleep function, so you can use fractional seconds
      (0.2 is the default, and provides a nice smooth animation,
      generally).

    seq

      Either a ref to an array containing your preferred spin character
      frames, or a scalar containing the name of your preferred spin
      character frames, from the available defaults. Because it re-draws
      the whole frame on each tick, very long frames may be unwieldy over
      slow connections. Several nice Unicode and ASCII frame sets are
      provided.

    color

      If provided, this will be the starting color of the spinner. It uses
      Term::ANSIColor color names, and the default is cyan.

    colorcycle

      If set to 1, or any truthy value, the colors will cycle through all
      seven of the base ANSI color values changing on each tick of the seq.

METHODS

    start

      Prints the first frame of the seq. Your cursor should be placed where
      you want the spinner to appear before starting. This method hides the
      cursor, so if interrupted, it may leave the terminal without a cursor
      (will be fixed sometime...).

    next

      Increments the seq and prints the next one. Call this method before
      or after each step in your program to show "progress". If you don't
      want to increment the indicator manually, you can use auto_start at
      the beginning of your long-running step or series of steps.

    done

      Resets the cursor to its original position and makes it visible. Call
      this when you are finished running your steps.

    auto_start

      Forks a new autonomous spinner process. It will print a spinner at
      the current cursor position until auto_done is called. If your
      program does not have many short steps, but instead one or more very
      long-running ones, this is likely preferable to the manual ticking
      process provided by start, next, and done.

    auto_done

      Call this method to end the current spinner process.

    run_ok

      This is a sort of weird method to eval one expression or a series of
      expressions in a list, with a spinner running throughout. At the end,
      it prints a Unicode checkmark or X to indicate success or failure.

      It currently only works with seq frames with length 1, 5, or 7. Any
      of the built-in spinner seq options will work with this method.

      It uses eval, so should not be given user-provided data or otherwise
      tricky stuff. It has no protections against shooting of feet.

BUGS

    Somewhat spotty on Windows shells (cmd.exe or PowerShell). PowerShell
    seems to have ANSI color support, but Unicode doesn't seem to work.

    Does not support multiple simultaneous spinners. It does not know how
    to find current spinner position or return to it. The program would
    likely need to make use of Curses, which is not in core, and is
    probably even less likely to work on Windows shells than the stuff I'm
    already using.

    Requires tput for the run_ok method to figure out the term column
    width.

    I have no idea how to write tests for this, so there's only a
    placeholder test.

