view release on metacpan or  search on metacpan

lib/App/column/run.pm  view on Meta::CPAN

package App::column::run;

our $AUTHORITY = 'cpan:PERLANCAR'; # AUTHORITY
our $DATE = '2021-07-08'; # DATE
our $DIST = 'App-column-run'; # DIST
our $VERSION = '0.005'; # VERSION

use 5.010001;
use strict;
use warnings;
use Log::ger;

use Text::Column::Util;

our %SPEC;

# TODO: color theme
# TODO: parallel execution
# TODO: streaming/immediate output

$SPEC{column_run} = {
    v => 1.1,
    summary => 'Run several commands and show their output in multiple columns',
    description => <<'_',

This utility is similar to using the Unix utility <prog:pr> to columnate output,
something like (in bash):

    % pr -T -m -w $COLUMNS <(command1 args...) <(command2 args...)

except with the following differences:

* commands are run in sequence, not in parallel (although parallel execution is
  a TODO list item);

* all output are collected first, then displayed (although streaming output is a
  TODO list item);

* multiplexing STDIN to all commands;

* ANSI color and wide character handling;

* passing adjusted COLUMNS environment to commands so they can adjust output;

* passing common arguments and environment variables to all commands (as well as
  allowing each command to have its unique arguments or environment variables).

_
    args => {
        %Text::Column::Util::args_common,
        commands => {
            'x.name.is_plural' => 1,
            'x.name.singular' => 'command',
            schema => ['array*', of=>'str*'], # XXX actually array of str is allowed as command
            req => 1,
            pos => 0,
            slurpy => 1,
        },
        common_args => {
            summary => 'Common arguments to pass to each command',
            description => <<'_',

If `--args-arrays` is also set, then the common arguments will be added first,
then the per-command arguments.

_
            'x.name.is_plural' => 1,
            'x.name.singular' => 'common_arg',
            schema => ['array*', of=>'str*'],
        },
        args_arrays => {
            summary => 'Arguments to give to each command (an array of arrays of strings)',
            schema => ['array*', of=>'aos*'],
            description => <<'_',

If `--common-args` is also set, then the common arguments will be added first,
then the per-command arguments.

_
        },
        common_envs => {
            summary => 'Common environment variables to pass to each command',
            'x.name.is_plural' => 1,
            'x.name.singular' => 'common_env',
            schema => ['hash*', of=>'str*'],
        },
        envs_arrays => {
            summary => 'Environment variables to give to each command (an array of hashes of strings)',
            schema => ['array*', of=>'hos*'],
        },
    },
    'cmdline.skip_format' => 1,
    links => [
        {url=>'prog:pr', summary=>'Unix utility to format and columnate text'},
        {url=>'prog:column', summary=>'Unix utility to fill columns with list'},
        {url=>'prog:diff', summary=>'The --side-by-side (-y) option display files in two columns'},

lib/App/column/run.pm  view on Meta::CPAN

}

1;
# ABSTRACT: Run several commands and show their output in multiple columns

__END__

=pod

=encoding UTF-8

=head1 NAME

App::column::run - Run several commands and show their output in multiple columns

=head1 VERSION

This document describes version 0.005 of App::column::run (from Perl distribution App-column-run), released on 2021-07-08.

=head1 DESCRIPTION

Sample screenshots:

=begin html

<img src="https://st.aticpan.org/source/PERLANCAR/App-column-run-0.005/share/images/Screenshot_20210625_085610.png" />

=end html


=begin html

<img src="https://st.aticpan.org/source/PERLANCAR/App-column-run-0.005/share/images/Screenshot_20210625_094844.png" />

=end html


=head1 FUNCTIONS


=head2 column_run

Usage:

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

Run several commands and show their output in multiple columns.

This utility is similar to using the Unix utility L<pr> to columnate output,
something like (in bash):

 % pr -T -m -w $COLUMNS <(command1 args...) <(command2 args...)

except with the following differences:

=over

=item * commands are run in sequence, not in parallel (although parallel execution is
a TODO list item);

=item * all output are collected first, then displayed (although streaming output is a
TODO list item);

=item * multiplexing STDIN to all commands;

=item * ANSI color and wide character handling;

=item * passing adjusted COLUMNS environment to commands so they can adjust output;

=item * passing common arguments and environment variables to all commands (as well as
allowing each command to have its unique arguments or environment variables).

=back

This function is not exported.

Arguments ('*' denotes required arguments):

=over 4

=item * B<args_arrays> => I<array[aos]>

Arguments to give to each command (an array of arrays of strings).

If C<--common-args> is also set, then the common arguments will be added first,
then the per-command arguments.

=item * B<commands>* => I<array[str]>

=item * B<common_args> => I<array[str]>

Common arguments to pass to each command.

If C<--args-arrays> is also set, then the common arguments will be added first,
then the per-command arguments.

=item * B<common_envs> => I<hash>

Common environment variables to pass to each command.

=item * B<envs_arrays> => I<array[hos]>

Environment variables to give to each command (an array of hashes of strings).

=item * B<linum_width> => I<posint>

Line number width.

=item * B<on_long_line> => I<str> (default: "clip")

What to do to long lines.

=item * B<separator> => I<str> (default: "|")

Separator character between columns.

=item * B<show_linum> => I<bool>

Show line number.