view release on metacpan or  search on metacpan

script/sudokug  view on Meta::CPAN

may be piped or redirected in (e.g.

 sudokug <commands

or

 cat commands | sudokug

) if the user so desires, with or without the -filter option.

Basically, any exposed method in Games::Sudoku::General is a command
understood by this script. Arguments to the methods are parameters
to the script commands. A few commands have been added to make life
for the user of the script easier.

Commands are parsed by Text::ParseWords, so the command name and
parameters are whitespace-delimited. Any parameter that contains
whitespace must be quoted. Either single ("'") or double ('"') quotes
will work.

Because some of the parameters (e.g. specifying a problem) involve a
large number of bytes, pseudo-"here documents" are supported. To
specify a "here document" as a parameter, specify "<<string" in place
of the parameter. The script will prompt with the string, and anything
you enter is part of that parameter, until you enter a line consisting
solely of the given string. More than one "here document" can be
specified; you will be prompted for them in left-to-right order. There
is an example of a "here document" in the L</SYNOPSIS> section.

Below is a brief description of the commands. For the attributes that
may be set or retrieved, and a more thorough (and possibly more
current) discussion of the underlying methods, see
L<Games::Sudoku::General>, or (equivalently) use the command

 sudokug> help lib

=head2 Commands

=head3 add_set

 sudokug> add_set main_diag 0 10 20 30 40 50 60 70 80

This command adds a set to an existing topology. The arguments are the
name of the new set, and the numbers of the existing cells that are to
be members of it.

Cells are numbered from 0 in the order in which they were defined by
the topology. Typically this is row order.

=head3 constraints_used

 sudokug> constraints_used

This command lists the constraints used to provide the most recent
solution.

=head3 copy

 sudokug> copy

Copy the current puzzle or solution to the clipboard. See the CLIPBOARD
SUPPORT section of the L<Games::Sudoku::General> documentation for what
you need to make this work.

=head3 drop_set

 sudokug> drop_set main_diagonal

This command drops a set from the existing topology. The argument is the
name of the new set.

=head3 exit

 sudokug> exit

This command does not correspond to a Games::Sudoku::General method.
It causes this script to terminate. Entering end-of-file in response
to a prompt by this script also works.

=head3 generate

 sudokug> generate 6 20 'F N'

This command attempts to generate a puzzle in the current topology. The
arguments are minimum number of givens, maximum number of givens, and
constraints to use.  All arguments may be defaulted, but the defaults
may not be appropriate for all topologies. See 'help lib' for details.

=head3 get

 sudokug> get topology

This command displays the values of the named attributes. You can
specify the name of more than one attribute. See L</Attributes> below
for a brief discussion of each, and L<Games::Sudoku::General> for more
details.

=head3 help

 sudokug> help

This command does not correspond to a Games::Sudoku::General method.
Without an argument, it gets you this documentation. If given with
the argument 'lib', that is, as

 sudokug> help lib

it gets you the POD for Games::Sudoku::General.

=head3 new

 sudokug> new

This command instantiates a Games::Sudoku::General object. You get one
for free when you launch this script; this command is for those cases
when it is easier to start over with a new object than to reconfigure
the one you already have. Any arguments get passed to the set() method.

=head3 paste

 sudokug> paste

Paste a new puzzle from the clipboard. See the CLIPBOARD SUPPORT
section of the L<Games::Sudoku::General> documentation for what you
need to make this work.

=head3 problem

 sudokug> problem <<EOD
 EOD: . . . 4 . . 7 8 9
 EOD: 4 . 6 . . . 1 . .
 EOD: . 8 . . . . . 5 .
 EOD: 2 . 4 . . 5 . . .
 EOD: . 9 5 . . . . . .
 EOD: . . . 9 . 2 3 4 5
 EOD: . 3 . . 7 . 9 . 8
 EOD: . 6 7 . . 1 . . .
 EOD: 9 . . . . 8 . . 2
 EOD: EOD

This command specifies the problem to be solved, in the order they were
defined by the topology (typically row order). The problem string must
be specified in terms of the currently-valid symbols. Whitespace
between the symbols is always allowed, but is required only if at least
one symbol consists of more than one character. Any invalid symbol is
taken to represent an unspecified cell.

Line breaks may be given (as in the L</SYNOPSIS>), but are treated
like any other whitespace.

=head3 set

 sudokug> set sudoku 3

This command sets each named attribute to its given value. You can
specify more than one name/value pair. See L</Attributes> below
for a brief discussion of each, and L<Games::Sudoku::General> for more
details.

In addition to the attributes of the L<Games::Sudoku::General> object
itself, the following pseudo-attributes are supported, and documented
below:

* webcmd - the name of the command to spawn to bring up a web browser.

=head3 show

 sudokug> show topology

This command does not correspond to a Games::Sudoku::General method,
but is just a synonym for 'get'.

=head3 solution

 sudokug> solution

This command causes an attempt to solve the currently-set-up problem.
If a solution is found, it will be displayed. Otherwise you will get
a brief message saying what happened.

If you issue this command more than once without an intervening
'problem' command, the solution will be attempted starting where the
previous solution left off. If there are multiple solutions to a

script/sudokug  view on Meta::CPAN

eliminated as a possibility for the given cells.

T naked size [[cell cell ...] value] ... - "naked tuple". The given
value is not possible for the given cell because there exists a "tuple"
(pair, triple, ...) of cells of the given size which must contain this
value, and the given cells are not in the tuple. More than one value
can be given, with a list of cells for each. The given value is
eliminated as a possibility for the given cells.

T hidden size [[cell cell ...] value] ... - "hidden tuple". The given
cells are part of a "tuple" of cells of the given size that must
contain a same-sized "tuple" of values, but the given values are not
part of the "tuple" of values that must be contained in those cells.
The given value is eliminated as a possibility for the given cell.

? [cell value] - "backtrack". If derivation of the solution reaches
a point where none of the above rules can be applied, we simply take
a guess at a legal cell value. The cell with the smallest number of
possible values is chosen for the guess. If there are more than one
such cell, the one with the smallest cell number is chosen. If at any
point a solution becomes impossible, we backtrack to the point we
took the guess, and try the next possible value.

=head3 unload

 sudokug> unload

Display the current problem, or its current solution if it has been
solved.

=head2 Attributes

Any readable attribute may be displayed with the 'get' or 'show'
commands, and any writable attribute may be set with the 'set'
command. For example:

 sudokug> set allowed_symbols <<EOD
 EOD: e=2,4,6,8
 EOD: o=1,3,5,7,9
 EOD: EOD
 sudokug>

The following simply lists the attributes. Rather than repeat their
definitions, you are simply referred to L<Games::Sudoku::General>, or
(equivalently) to the

 sudokug> help lib

command.

=over

=item allowed_symbols (string)

This attribute is used to specify and name sets of allowed symbols. See
above for an example.

=item autocopy (boolean)

If true (in the Perl sense) generated problems are copied to the
clipboard.

=item brick (string, write-only)

This pseudo-attribute sets the topology, symbols, and columns for a
Sudoku puzzle involving rectangular regions rather than square ones.
The value is a comma-delimited string of three numbers representing
the horizontal and vertical dimensions of the rectangular regions, and
the size of the enclosing square.

The last number may be omitted, with the default being the product of
the first two. It is in fact deprecated, with the intent of disallowing
it in the future.

=item columns (number)

This attribute specifies the number of cells displayed on a line of
topology or solution output. It has nothing to do with the problem
itself, and no effect on problem input.

=item corresponding (number)

This pseudo-attribute sets the topology, symbols, and columns for a
Sudoku puzzle having the additional restriction that corresponding
cells in the small squares must contain different numbers. The value
is the size of the small square (i.e. the same as the value for
C<sudoku>). Also called "disjoint groups".

=item cube (string, write-only)

This pseudo-attribute sets the topology, symbols, and columns for a
Sudoku puzzle on the faces of a cube. There are three topologies
supported; two on the face of a 4 x 4 x 4 cube, plus the Dion cube.
Which one is actually generated is selected by the argument:

* a number generates a Dion cube, and specifies the size of the small
square. Specifying 3 generates a 9 x 9 x 9 Dion cube.

* 'full' generates a puzzle on all 6 faces of the cube. The sets are
the faces of the cube and the "stripes" of cells running around the
cube in all three directions. The problem is entered face-by-face;
if you imagine the cube unfolded into a Latin cross, work top-to-bottom
and left-to-right.

* 'half' generates a puzzle on the visible 3 faces of an isometric view
of a cube. The sets are halves of the face and the visible "stripes".
Imagine the visible part of the cube unfolded into the letter "L", with
the top and right faces divided horizontally, and the remaining face
divided vertically. Enter the problem working top-to-bottom and
left-to-right.

B<Caveat:> The symbols generated for a 'full' cube are 1 .. 16. The
example I have (from L<http://www.mathrec.org/sudoku/sudokucube.gif>)
uses 0 through F. If you have one of these, remember to 'set symbols'
after you 'set cube full'.

See L<Games::Sudoku::General> (or 'help lib') for a fuller discussion,
with cheesy typed diagrams.

=item debug (number)