view release on metacpan or  search on metacpan

lib/Games/Sudoku/PatternSolver/Generator.pm  view on Meta::CPAN

=head1 NAME

Games::Sudoku::PatternSolver::Generator - produces 9x9 Sudoku solution grids and 9x9 Sudoku puzzles

=head1 DESCRIPTION

This sub module uses the L<Games::Sudoku::PatternSolver>'s POM ability (Pattern Overlay Method) to build solution grids 
and enables L<PatternSolver::CPLogic|Games::Sudoku::PatternSolver/"PatternSolver::CPLogic"> to provide some indication of rating with the generated puzzles.

You may supply a grid of your liking to begin with, but it really doesn't matter because it is the (always) 
random order in which cell values are tried to be removed that make the essential difference, not the grid at launching point.

All Sudoku that are returned from the iterator I<builder> are well-posed (have a unique solution) and reduced (removing any of the givens would lead to > 1 solution).

=head1 METHODS

=head2 get_sudoku_builder()

 $sudoku_builder = get_sudoku_builder( start_grid, start_with, shuffle_symbols );

All 3 parameters are optional:

=over 4

=item * start_grid (default none)

A grid string (81 chars) to start from, typically a complete solution as produced by the L<grid_builder|get_grid_builder>.

If a start grid is passed, the iterator will never replace it with another one. 
It will just be used over and over again, values removed in another random sequence.
The generated puzzles in this case, despite being all different in nature, will all share the same solution.

If you pass a grid with any missing values (a puzzle) it will just be checked and reported if the puzzle could be reduced any further and still be well-formed.   

=item * start_with (default 40)

Number of random values to drop from the grid before checking the number of solutions for uniqueness kicks in.
A smaller number could lead to more unnecessary solution checking up front.
Too big a number might start the checking too often on a grid already overly reduced, which has more than one solution and has thus to start over.

=item * shuffle_symbols (default true)

If false (and no start_grid was given), all puzzle's solutions will have the first row '123456789'. 

=back

The return value $sudoku_builder is a subref which on every call will return a result hash from its last call to L<Patternsolver::solve()|Games::Sudoku::PatternSolver/"solve()">:

 while (my $puzzle = &$sudoku_builder()) { 
 		... inspect and either reject or do something with $puzzle
 		print $puzzle->{strPuzzle}; 
 }

=head2 get_grid_builder()

 $grid_builder = get_grid_builder();
 $solution_string = &$grid_builder( <shuffle_symbols> ); 

The iterator returned from get_grid_builder() can produce fully filled sudoku grids at a fairly high rate. 
Like the solver, it also uses plain overlay of random patterns (POM) and no biased methods. (As the Latin Squares would.) 
The grids are spread absolutely randomly across the Sudoku space.

=head1 EXPORTS

The module optionally exports get_sudoku_builder(), get_grid_builder() and provides the import tag ':all'.

=head1 SCRIPTS

=head2 sudogen

After installation of Games::Sudoku::PatternSolver this command line script should be in your path.
Flexible output options are available. Invoke C<E<gt>sudogen -h> for details.

=head1 SEE ALSO

L<Games::Sudoku::Html> to play entire lists of standard sudoku interactively in your browser 

L<Games::Sudoku::Pdf> to create pdf files from sixteen variants of 9x9 sudoku

=head1 AUTHOR

Steffen Heinrich

=head1 LICENSE

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

=cut