/ 
App-hr-0.268
River stage one • 2 direct dependents • 2 total dependents
/ App::hr

NAME

App::hr - Print horizontal bar on the terminal

VERSION

This document describes version 0.268 of App::hr (from Perl distribution App-hr), released on 2022-09-03.

SYNOPSIS

use App::hr qw(hr hr_r);
hr;

Sample output:

=============================================================================

Set pattern:

hr('x----');

Sample output:

x----x----x----x----x----x----x----x----x----x----x----x----x----x----x----x-

Use random color and random pattern:

hr_r;

You can also use the provided CLI hr.

DESCRIPTION

A demo screencast:

FUNCTIONS

hr([ $pattern [, $color ] ]) => optional STR

Print (under void context) or return (under scalar/array context) a horizontal ruler with the width of the terminal.

Terminal width is determined using Term::Size.

$pattern is optional, can be multicharacter, but cannot be empty string. The defautl is =.

Under Windows, will shave one character at the end because the terminal cursor will move a line down when printing at the last column.

If $color is set (to a color supported by Term::ANSIColor) and colored output is enabled, output will be colored. Colored output is enabled if: 1) no NO_COLOR environment variable is defined; 2) COLOR is undefined or true, or program is run interactively.

hr_r => optional STR

Like hr, but will set random pattern and random color.

hr_Br => optional STR

Like hr, but will set random pattern and random color and return a blinking bar.

hr_app

Usage:

hr_app(%args) -> [$status_code, $reason, $payload, \%result_meta]

Print horizontal bar on the terminal.

hr can be useful as a marker/separator, especially if you use other commands that might produce a lot of output, and you need to scroll back lots of pages to see previous output. Example:

% hr; command-that-produces-lots-of-output
============================================================================
Command output
...
...
...

% hr -r; some-command; hr -r; another-command

Usage:

% hr
============================================================================

% hr -c red  ;# will output the same bar, but in red

% hr --random-color  ;# will output the same bar, but in random color

% hr x----
x----x----x----x----x----x----x----x----x----x----x----x----x----x----x----x

% hr -- -x-  ;# specify a pattern that starts with a dash
% hr -p -x-  ;# ditto

% hr --random-pattern
vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv

% hr --random-pattern
*---*---*---*---*---*---*---*---*---*---*---*---*---*---*---*---*---*---*---

% hr -r  ;# shortcut for --random-pattern --random-color

% hr -Br ;# a BLINKING random pattern, random color bar

% hr --help

If you use Perl, you can also use the hr function in App::hr module.

This function is not exported.

Arguments ('*' denotes required arguments):

  • blink => bool

    Return a blinking bar.

  • color => str

    Specify a color (see Term::ANSIColor).

  • height => int (default: 1)

    Specify height (number of rows).

  • pattern => str

    Specify a pattern.

  • random_color => bool

  • random_pattern => bool

  • space_after => int (default: 0)

    Number of empty rows after drawing the bar.

  • space_before => int (default: 0)

    Number of empty rows before drawing the bar.

Returns an enveloped result (an array).

First element ($status_code) is an integer containing HTTP-like status code (200 means OK, 4xx caller error, 5xx function error). Second element ($reason) is a string containing error message, or something like "OK" if status is 200. Third element ($payload) is the actual result, but usually not present when enveloped result is an error response ($status_code is not 2xx). Fourth element (%result_meta) is called result metadata and is optional, a hash that contains extra information, much like how HTTP response headers provide additional metadata.

Return value: (any)

ENVIRONMENT

NO_COLOR

COLOR

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/App-hr.

SOURCE

Source repository is at https://github.com/perlancar/perl-App-hr.

SEE ALSO

ruler (App::ruler)

AUTHOR

perlancar <perlancar@cpan.org>

CONTRIBUTOR

Steven Haryanto <stevenharyanto@gmail.com>

CONTRIBUTING

To contribute, you can send patches by email/via RT, or send pull requests on GitHub.

Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via:

% prove -l

If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE

This software is copyright (c) 2022, 2021, 2020, 2018, 2016, 2015, 2014 by perlancar <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.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=App-hr

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.