#!/usr/bin/perl
use 5.016;
use strict;
use warnings;

use App::Tarotplane;

my $tarotplane = App::Tarotplane->init();

$tarotplane->run();



=head1 NAME

tarotplane - Curses flashcard program

=head1 SYNOPSIS

  tarotplane [options] file ...

=head1 DESCRIPTION

B<tarotplane> is a TUI flashcard program written in Perl using the Curses
module. It reads cards from specially formatted text files consisting of terms
and definitions, then displays them in a TUI.

=head2 Card Files

A B<tarotplane> card file is a text file that contains cards. Each card must
contain a term and definition, which are seperated by a colon (:). Terms
precede the colon, definitions follow the colon Cards are.
seperated from each other by a delimitting line, which is a line that only
contains a percentage (%) sign. Any whitespace found in the terms and
definitions will be truncated to a single space character. Leading and trailing
whitespace for terms/definitions are trimmed. A detailed example card file can
be found in the EXAMPLES section of this manual.

Empty cards are ignored and will not throw an error. This means if you have a
card file like this:

  %
  Term 1: Definiton 1
  %
  %
  %
  Term 2: Definition 2
  %

B<tarotplane> will only read two cards, and ignore the two empty cards between
Term 1 and Term 2.

Lines starting with a hash (#) are treated as comments and are ignored. Blank
lines are also ignored.

=head3 Escape Sequences

An escape sequence is a pair of characters, a forward slash (\) and some other
character, that signals to B<tarotplane> to perform special behavior when
reading/displaying the card. Below is a list of all the escape sequences
B<tarotplane> supports:

=over 4

=item \\

Single back slash (\).

=item \:

Colon (:).

=item \n

Force linebreak.

=back

=head2 Controls

The controls for B<tarotplane> can be viewed during runtime by entering '?'.

=over 4

=item B<Right Arrow>, B<l>

Next card.

=item B<Left Arrow>, B<h>

Previous card.

=item B<Space>, B<Up/Down Arrow>, B<j/k>

Flip to other side.

=item B<Page Down>, B<End>

Go to last card.

=item B<Page Up>, B<Home>

Go to first card.

=item B<q>

Quit.

=item B<?>

Help screen for controls.

=back

=head1 OPTIONS

=over 4

=item B<-o> [I<by>], B<--order>[=I<by>]

Order cards to appear alphabetically. I<by> can either be 'Term' or
'Definition' (case-insensitive) to specify which sides to compare when ordering.
If I<by> is not specified, defaults to sorting by terms.

=item B<-r>, B<--random>

Randomizes the order the cards appear in.

=item B<-t>, B<--terms-first>

Show terms first rather than definitions.

=item B<-h>, B<--help>

Print help message and exit.

=item B<-v>, B<--version>

Print version and copyright information, then exit.

=back

=head1 EXAMPLES

An example of a valid card file:

 # American authors
 %
 Thomas Pynchon:
 Author of Gravity's Rainbow, V, and The Crying of Lot 49.
 %
 Joseph Heller:
 Author of Catch-22.
 %
 John Steinbeck:
 Author of East of Eden, Of Mice and Men, and Grapes of Wrath.
 %
 Cormac McCarthy:
 Author of Blood-Meridian, No Country For Old Men, and The Road.
 %
 Herman Melville:
 Author of Moby-Dick, Billy Budd the Sailor, and Bartleby the
 Scrivener.
 %

 # Russian authors
 %
 Leo Tolstoy:
 Author of War and Peace, Anna Karenina, and Death of Ivan Ilyich.
 %
 Fyodor Dostoevsky:
 Author of Crime and Punishment, Notes from the Underground, and The
 Brothers Karamazov.
 %
 Aleksander Solzhenitsyn:
 Author fo One Day in the Life of Ivan Denisovich.
 %
 Vladimir Nabokov:
 Author of Lolita and Pale Fire.
 %

=head1 AUTHOR

Written by Samuel Young E<lt>L<samyoung12788@gmail.com>E<gt>.

=head1 COPYRIGHT

Copyright 2024, Samuel Young.

This program is free software; you may redistribute it and/or
modify it under the same terms as Perl itself.

=cut
