NAME
Games::Sudoku::Preset - enter, edit or validate the preset values of a Sudoku puzzle.
VERSION
This documentation refers to Games::Sudoku::Preset version 0.0.1.
SYNOPSIS
use Games::Sudoku::Preset;
# Enter the preset values for a new Sudoku puzzle
my $puzzle = Games::Sudoku::Preset->enter();
# Edit an existing Sudoku puzzle
my $puzzle = Games::Sudoku::Preset->edit($game);
# Validate an existing Sudoku puzzle
my $puzzle = Games::Sudoku::Preset->validate($game);$game is either a string (possibly with embedded newlines) or a reference to an array of strings.
$puzzle is a string of 81 characters, representing a validated Sudoku puzzle.
DESCRIPTION
This section describes the common behaviour of the three public start methods. Special behaviour of a specific start method is described in section "METHODS".
In general module Games::Sudoku::Preset works in 4 steps:
Purify (convert to a string of 81 characters)
Verify (check for errors, display errors on the board)
Edit (let the user edit the puzzle)
Return (Verify the edited puzzle, return if no errors found)
Purify the given puzzle
When the puzzle is passed as a reference to an array, this is joined to a string. The number and positions of newlines in the string doesn't matter: all newlines are removed. If the string is now longer than 81 characters, all whitespace is removed. Now the string must be exactly 81 characters long. Otherwise the string is written to STDERR together with an error message, and an empty string is returned to the caller.
Verify the specified puzzle
The puzzle is checked for violation of the well known Sudoku rules (e. g. twice the same value in a row). When an error is found, a message is displayed below the Sudoku board of the GUI, and the affected fields are marked by red color on the board. The user may now correct the error. Editing of the board is described in detail in section "EDIT THE SUDOKU BOARD".
The editing phase
The user edits the puzzle in the GUI board according to his needs. This is described in detail in section "EDIT THE SUDOKU BOARD".
Return of the edited puzzle
The user clicks on the Done button to leave Games::Sudoku::Preset. First the current state of the puzzle is verified again to ensure that it is ok. When an error is found, Games::Sudoku::Preset shows this on the board and stays in the editing phase. Otherwise the current puzzle is returned, using the first placeholder of the original puzzle as the placeholder for unknown values.
METHODS
This section describes specific behaviour of the public start methods.
enter
Method Games::Sudoku::Preset->enter initially displays an empty Sudoku board. The user may immediately start entering values, as described in section "EDIT THE SUDOKU BOARD".
The returned puzzle has "-" as the placeholder for unknown values.
edit
Method Games::Sudoku::Preset->edit displays the initially verified puzzle on the Sudoku board, whether with or without errors. The user may immediately start editing it, as described in section "EDIT THE SUDOKU BOARD".
validate
Method Games::Sudoku::Preset->validate returns the initially verified puzzle immediately when no errors are found. The GUI is not shown in this case.
EDIT THE SUDOKU BOARD
This section describes the usage of the Sudoku board. Editing may be done via the mouse or via the keyboard.
Editing via the mouse
When the mouse cursor enters a field of the board, this field gets covered by a 3x3 grid of tiny squares. Each square corresponds to one of the digits 1 to 9. If the field already contains a value, the corresponding square is shown in red.
Clicking on one of the black squares inserts the corresponding digit as the value of the field. So you can select a field and a digit with a single mouse click (I am very proud on this invention). Any previous value of the field will be replaced. Clicking on the red square will remove the corresponding value from the field.
Editing via the keyboard
The input focus may be moved to an adjacent field by the arrow keys (end around). A value may be entered in the active field by the keys 1 to 9 (on the alpha or numeric keypad). This will replace any previous value in the field. A value may be deleted by the keys 0, Delete, or the Space bar.
Pressing any of the supported keys will also hide the 3x3 grid.
TERMINATING THE MODULE
The GUI of Games::Sudoku::Preset shows three buttons for termination.
The Done button causes validation of the current state of the puzzle. When no errors are found, it is returned to the caller.
The Cancel button causes termination of the program. No output is generated.
The Save & Cancel button lets you save the current state of the puzzle in a file before terminating the program. You may later continue to edit it.
The standard kill button (at the right side of the title bar) acts like the Cancel button.
TRANSFORMATIONS OF THE RETURNED PUZZLE
The puzzle is returned as a string of 81 characters. According to the needs of the program, these transformations may be used:
Change the placeholder
$puzzle =~ tr/-/<my_placeholder>/;Change to string of 9 lines with 9 characters each
(my $puzzle9x9 = $puzzle) =~ s/(.{9})(?=.)/$1\n/g;Change to array of 9 elements with 9 characters each
my @puzzle9x9; while ($puzzle) {push @puzzle9x9, substr($puzzle, 0, 9, '')};
RESTRICTIONS
The placeholders in the given Sudoku puzzle must be printable ASCII characters.
For historical reasons "#" shouldn't be used as the first placeholder.
DEPENDENCIES
http://search.cpan.org/perldoc?Tk (Perl/Tk)
BUGS
Please report bugs using <http://rt.cpan.org>. Patches are welcome.
AUTHOR
Klaus Wittrock (<Wittrock [at] cpan.org>)
LICENCE AND COPYRIGHT
Copyright 2014 Klaus Wittrock. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.