The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Games-Sudoku-Pdf-0.04
River stage zero No dependents
++
/ Games::Sudoku::Pdf

NAME

Games::Sudoku::Pdf - Produce pdf files from your digital Sudoku sources or collections.

DESCRIPTION

An easy way to create pdf files of 9x9 Sudoku puzzles from various sources, which you can give to your friends or print out and pencil solve at the beach. Sixteen variants of 9x9 Sudoku are supported. (See the output of scripts/example.pl.) Just specify how many puzzles (columns x rows) to arrange per page and the positioning and scaling will be adapted automatically.

SYNOPSIS

  my $writer = Games::Sudoku::Pdf->new(%options);

  $writer->add_puzzle(
    clues      => '.9.46.....85...4.7..........3.2.8.4...9...1...6.1.4.5..........3.4...92.....49.8.', 
    jigsaw     => '111222333141122333141226663441522563745555563745885966744488969777889969777888999', 
    extraRegion => 'g',
    bottomLine  => 'jigsaw #5 from Daisy (very hard!)',
  );

  $writer->read_input_file('./all-17-clues-sudoku.txt', slice => [5..9, 7..25]);

  $writer->close();

  >sudoku2pdf my_sudokus.txt > my_sudokus.pdf

METHODS

new()

  Games::Sudoku::Pdf->new( %options )

Returns the writer object. The following options are available:

pageFormat default 'A4'

Find possible values in PDF::API2::Resource::PaperSizes.

pageOrientation

Possible values are 'portrait' or 'landscape'. Default is the resp. format's definiton in PDF::API2::Resource::PaperSizes.

puzzlesPerPage default 4 (resolved to '2x2')

Specifies the number of Sudoku per page, their size and positions. You will probably want to give the WxH notation. If you specify e.g. '1x5', 5 small Sudoku will be placed at the left side, leaving place for your manual notes to the right. Once you specify 2 or more columns, they will get equally distributed from left to right.

appendFile

You can specify path and name of any existing pdf file, to which the new pages shall be appended.

title, author, subject, keywords

Any of these four optional values will be written to the pdf meta data fields.

extraRegion default none

For Sudoku sporting an 'extra region' (X-, Hyper-, Percent- ...) this parameter can be given globally here, or for each puzzle added. The following variants are recognized:

x X-Sudoku
h Hyper Sudoku
p Percent Sudoku
c Color Sudoku

Just one fixed version is currently possible (colors 1-9):

  +-------------------+
  | 1 2 3 1 2 3 1 2 3 |
  | 4 5 6 4 5 6 4 5 6 |
  | 7 8 9 7 8 9 7 8 9 |
  | 1 2 3 1 2 3 1 2 3 |
  | 4 5 6 4 5 6 4 5 6 |
  | 7 8 9 7 8 9 7 8 9 |
  | 1 2 3 1 2 3 1 2 3 |
  | 4 5 6 4 5 6 4 5 6 |
  | 7 8 9 7 8 9 7 8 9 |
  +-------------------+
d Center Dot Sudoku
a Asterisk Sudoku
g Girandola Sudoku

For an overview take a look at the script and output of "example.pl" in scripts.

add_puzzle()

  $writer->add_puzzle(%options)

Adds the next puzzle to the pdf. The options are:

clues mandatory

A string of 81 characters, the common Sudoku exchange format. Given clues as numbers 1-9, empty cells denoted by ., 0, space or any non-digit.

jigsaw optional

Instead of regular 3x3 boxes with straight sides, the puzzle can be broken up into irregular shapes. These may be provided by a string of 81 characters with the numbers 1-9 whose positions form 9 contiguous areas in the puzzle matrix. Refer to example.pl.

extraRegion default none

A single letter of xhpcdag, as described in extraRegion above.

bottomLine default none

A short string which will be put beneath the puzzle. You may want to provide the puzzle's source, its estimated difficulty, a number or anything else. Because we use the pdf corefonts, only latin1 is supported.

It is up to you and your Sudoku sources, that the given clues together with the other optional parameters provided defines a proper puzzle with exactly one solution.

read_input_file()

  $writer->read_input_file($input_file, %options)

A convenience method to slurp an entire text file with your puzzle collection. The $input_file may be a file name or an open handle. The %options are:

slice optional

An array reference that contains the numbers of the puzzle lines that will be processed. Only lines starting with a string of 81 givens are counted. Or, if you provided a lineHandler, for which the handler returned a hashref.

lineHandler optional

A reference to your custom subroutine thats given the chomp-ed line and has to return a hashref that will be fed to add_puzzle(). If the return value is false, the line is skipped.

If no custom line handler is provided, lines are expected to follow the format

  <81 char givens> [<delim> [<81 char jigsaw>] [<delim> [<1 char extraRegion>] [<delim> [<bottomLine>]]]]

Delimiters can be '|', ':', ',', ';', <tab>. For any standard Sudoku, the givens alone are sufficient. See the 4 parameter's descriptions to add_puzzle().

Note: If this somewhat limited input format does not suit you, take a look at the commandline script sudoku2pdf.

page_break()

  $writer->page_break()

Continue adding puzzles on a new page with otherwise unchanged settings. There will be no empty pages inserted by repeated calls.

close()

  $writer->close( $output_file )

Writes the pdf to file and frees memory. The $output_file may be omitted if an 'appendFile' was specified in new() and if that file is supposed to be replaced. Any existing files will get overwritten without a warning!

SCRIPTS

sudoku2pdf

After installation of Games::Sudoku::Pdf this command line script should be in your path. Flexible input options are available. Invoke >sudoku2pdf -h for details.

DEPENDENCIES

SEE ALSO

Games::Sudoku::PatternSolver::Generator, Games::Sudoku::Html

COPYRIGHT AND LICENSE

The following copyright notice applies to all the files provided in this distribution, including binary files, unless explicitly noted otherwise.

This software is copyright (c) 2024 by Steffen Heinrich

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.