#!/usr/bin/env perl

use strict;
use warnings;
use App::Cleo::Patra;

our $VERSION = 0.001;

#-----------------------------------------------------------------------------

die 'Usage: patra [-m] COMMAND_FILE' if not @ARGV;
my $patra = App::Cleo::Patra->new;

my $multiline = 0;
if ($ARGV[0] eq '-m') {
    $multiline = 1;
    shift @ARGV;
}

$patra->run(shift, $multiline);
exit;

#-----------------------------------------------------------------------------

=pod

=encoding utf8

=head1 NAME

patra - Play back shell commands for live demonstrations

=head1 SYNOPSIS

    patra [-m] COMMAND_FILE

=head1 DESCRIPTION

B<Important:>
C<patra> is an experimental fork from C<cleo>.
You should check the current differences from C<App-Cleo> and decide, which one you want to use.
It may be, that in your current time, C<patra> is merged back into C<cleo> or obsolete for other reasons.

C<patra> is a utility for playing back pre-recorded shell commands in a live
demonstration.  C<patra> displays the commands as if you had actually typed
them and then executes them interactively.

There is probably an easy way to do this with C<expect> or a similar tool.
But I couldn't figure it out, so I built this.  Your mileage may vary.

=head1 PLAYBACK

C<patra> pauses and waits for a keypress before displaying a command and
before executing it. Pressing any key besides those listed below will advance
the playback:

  Key                       Action
  ------------------------------------------------------------------
  s                         skip the current command
  r                         redo the current command
  p                         redo the previous command
  c                         run all remaining commands
  q                         quit playback
  [number][not a digit]     jump to specific command number

=head1 COMMANDS

C<patra> reads commands from a file.  Each line is treated as one command.
Blank lines and those starting with C<#> will be ignored.  The commands
themselves can be anything that you would type into an interactive shell.
You can also add a few special tokens that C<patra> recognizes:

=over 4

=item C<!!!>

Commands starting with C<!!!> (three exclamation points) are not displayed and
will be executed immediately. This is useful for running setup commands at the
beginning of your demonstration.

=item C<...>

Commands starting with C<...> (three periods) will be executed without waiting for a keypress. This is useful if you want to show a series of commands but don't need to stop and explain each one as you go.

=item C<%%%>

Within a command, C<%%%> (three percent signs) will cause playback to pause and
wait for a keypress before displaying the rest of the command.  This is useful
if you want to stop in the middle of a command to give some explanation.

=item C<$ >

This syntax is only supported, when you start C<patra> with the option C<-m>.
You then should preceed each commend with C<$ > (C<Dollar>, C<Space>).
Your advantage then is, that you can scatter your commands over mutliple lines, as far as Bash can handle it.

=back

Otherwise, C<patra> displays and executes the commands verbatim.  Note that
some interactive commands like C<vim> are picky about STDOUT and STDIN.  To
make them work properly with C<patra>, you may need to force them to attach
to the terminal like this:

    (exec < /dev/tty vim)

=head1 EXAMPLE

Ryan uses this for giving demonstrations of L<pinto>, such as the one seen at
L<https://www.youtube.com/watch?v=H-JkFXm8Xgk> (the live demonstration part
starts around 10:47).

The command file that I use for that presentation is included inside this
distribution at F<examples/pinto.demo>.  This file is for illustration only,
so don't expect it to actually work for you.

=head1 LIMITATIONS

C<patra> only works on Unix-like platforms.

=head1 TODO

=over 4

=item Support backspacing in recorded command

=item Write unit tests

=back

=head1 AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

Boris Däppeb (BORISD) <bdaeppen.perl@gmail.com>

=head1 COPYRIGHT

cleo - Copyright (c) 2014, Imaginative Software Systems

patra - Boris Däppen (BORISD) 2018

=cut
