NAME
    Game::Lottery

VERSION
    version 1.03

DESCRIPTION
    Pick and check numbers for popular Lottery Draw Games using a
    Cryptographically Secure randomizer.

    General Draw Games and Big Draw Games are supported, but ticket
    valuation functions are only available for PowerBall and MegaMillions.

SYNOPSIS
    Use the bundled lottery-big-draw.pl script to pick your numbers:

      lottery-big-draw.pl -h

    To use in your code:

      use Game::Lottery;
      my $lottery = Game::Lottery->new( game => 'PowerBall');

DRAW GAMES
    Lottery Draw games have a pool of balls. Players bet on as many numbers
    as the number of balls that will be drawn.

BIG DRAW LOTTERY GAMES
    Have a pool of balls (white) players must match, and a second pool (red)
    from which (usually) a single ball is drawn, many of the prizes require
    matching the red ball.

    The odds of winning the big prize in the two main games in the United
    States: PowerBall and MegaMillions, are about 300 Million to 1. When the
    prize isn't won, the jackpot increases. The JackPots frequently get
    quite large. When the JackPots get large enough, the expected value of a
    ticket exceeds the cost. The smaller prizes in both US games return less
    than 20% of the ticket value.

    There are several options to increase bet sizes, both major games have a
    multiplier ball option; these are not currently supported.

    California has a different payout on non-jackpot prizes. For California
    and any other jurisdictions not using the standard payout table, the
    expected value generated by this software does not apply.

METHODS
  new
    Required parameter: game

    Games currently supported are PowerBall, MegaMillions, Draw (1 ball
    pool) and CustomBigDraw(custom 2 ball pools). Game names may be
    abbreviated as mega, power, draw and custom.

      my $game = Game::Lottery->new( game => 'PowerBall');
      my $game = Game::Lottery->new( game => 'power');

  Game
    Returns the Game.

      say $game->Game();

  BasicDraw
    Returns an Array Reference of balls picked. Applicable to a large number
    of Draw games.

      my $drawn = $game->BasicDraw( $BallLastNum, $BallsDrawn );

  BigDraw
    Draws White and Red Balls for Big Draw Games.

    Returns a Hash Reference.

      my $drawn = $game->BigDraw();

      {
        game => $game,
        whiteballs => ArrayRef,
        redballs => ArrayRef
      }

  CustomBigDrawSetup
    For CustomBigDraw games, the pool ranges and number of balls to draw
    must be set before using the BigDraw method. For the directly supported
    Big Draw Games this is done at new. The game name is set to
    CustomBigDraw

      $game->CustomBigDrawSetup(
        game => 'Some other big draw game', # optionally set a custom game name.
        white => 99,
        whitecount => 1,
        red => 20,
        redcount => 5
    );

  TicketValue
    Returns the expected value of a ticket given a JackPot. The Cash Value
    should be used, not the advertised annuity value. The value passed may
    be either in dollars or millions of dollars. If no value (or 0) is based
    the result will be the return of all other prizes than the jackpot.

      my $TicketValue = $game->TicketValue( 600 );
      my $BaseTicketValue = $game->TicketValue( 0 );

  TicketJackPotValue
    Returns just value of the JackPot divided by the number of possible
    combinations.

      my $JackPot = $game->TicketJackPotValue( 600 );

  SavePicks
    Save an arrayref of picks from BasicDraw or BigDraw to a file.

      $game->SavePicks( $file, $picks );

  ReadPicks
    Read saved picks from a file, returns an array.

      my @picks = $game->ReadPicks( $file );

Checking Tickets
  CheckPicks
      say join "\n", $game->CheckPicks( $winnersfile, $ticketsfile );

  The Saved Tickets File Format
    This library pads single digit numbers with a leading 0. It uses [] to
    differentiate red balls. The balls are checked as strings so 01 and 1
    are not matching numbers just as 02 and [02] are not. The entries are
    simply the numbers on a line, separated by spaces, with the red balls in
    [brackets].

    A file generated by SavePicks looks like this:

      05 40 50 57 60 [15]
      02 33 36 44 68 [19]

    The format allows for a memo at the beginning of a line, separated from
    the data by a double colon ::. When included in a winners file, the memo
    is included in the output. Usually the memo is the date of the draw, but
    it can be any string. Lines beginning with # are considered comments and
    not read.

    Winners files need to be created by hand.

      # example winners file
      2023-09-16:: 22 30 37 44 45 [18]
      # the memo is just a string, it doesn't have to be the date
      Wednesday 2023-10-11::22 24 40 52 64 [10]
      # the memo isn't required but is helpful when you have
      # multiple lines in your winners file.
      16 34 46 57 59 [23]

SEE ALSO
    You can allow the Lottery to pick numbers for you, which will save you
    from having to put numbers you picked onto the slips for the lottery
    machines. If you search the web and the mobile app stores, you'll find
    plenty of sites and apps that do similar things to this module.

AUTHOR
    John Karr BRAINBUZ <https://metacpan.org/author/BRAINBUZ>

  CONTRIBUTORS
BUGS
    Please report any bugs or feature requests through the web interface at
    <https://bitbucket.org/brainbuz/lottery/issues>. I will be notified, and
    then you'll automatically be notified of progress on your bug as I make
    changes.

TODO
    The most interesting thing todo would be to use an API to get winning
    ticket data. There are several providers that require registering for a
    key. The author would prefer to use a keyless api, preferably provided
    by the major games or one of the state lotteries. The major games do not
    provide such an API.

LICENSE AND COPYRIGHT
    Copyright 2023 John Karr.

    This program is free software: you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by the
    Free Software Foundation, either version 3 of the License, or (at your
    option) any later version.

    This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
    Public License for more details.

    You should have received a copy of the GNU General Public License along
    with this program. If not, see <http://www.gnu.org/licenses/>.

