This is a Sudoku number puzzle game written in Common Lisp.  At its
most basic, it produces puzzles which the user can solve.  On the GNU
Clisp and platform with screen support, or SBCL with UFFI and ncurses,
it becomes a full-screen interactive game.

The file "generate.lisp" exports a package called "NUMBER-PUZZLE", and
several symbols within those:
MAKE-PUZZLE      - constructs a new puzzle, produces no output
SHOW-PUZZLE      - prints the puzzle, guaranteed to have a unique solution
SHOW-SOLUTION    - prints the solution to the puzzle
PRINTED-PUZZLES  - produces a LaTeX output file with puzzles and
		   solutions on different pages, typically 10 to a
		   sheet.

In any conformant lisp, it should be possible to execute the
following:

(compile-file "generate")
(load "generate")
(number-puzzle:make-puzzle)
(number-puzzle:show-puzzle)

then, you can work out the solution on paper, in an emacs window, or
whatever, and finally check your result with

(number-puzzle:show-solution)

If you want to print out a bunch of puzzles for a trip or something,
you can simply run:

(number-puzzle:printed-puzzles "output-file-name")

The output file is a LaTeX document that will, on US Letter paper,
produce 10 puzzles and 10 solutions, on separate pages.  The
"PRINTED-PUZZLES" function takes an optional second argument, the
number of puzzles to produce, so:

(number-puzzle:printed-puzzles "output-file-name" 100)

would print 10 pages of puzzles, and 10 of solutions.

The puzzles are usually quite hard.


The system is semi-hard-coded for 9x9 puzzles.  In principle, this can
changed by modifying *puzzle-size* and *colour-array*, but the output
methods and interactive code currently assume 9x9 puzzles.


Interactive mode (SBCL or CLISP):
=================================

With clisp, compiled with screen support, one can run an ncurses-based
full-screen version of the program.  This is done by executing:

$ clisp -q -x "(progn (asdf:operate 'asdf:load-op 'puzzle) (screen-puzzle))"

With SBCL, with UFFI and CL-NCURSES, one can run an ncurses-based
full-screen version of the program.  This is done by executing:

$ sbcl --eval "(progn (require 'cl-ncurses) (asdf:operate 'asdf:load-op 'puzzle) (screen-puzzle) (quit))"



Here, the screen displays the puzzle, and allows you to fill in
cells.  The 'H' key gets help.  Some useful features to note:
- There is a push/pop state command, you can push state and make a
  guess, filling in cells.  If you discover you have made the wrong
  guess, you can pop back to the state you pushed.  The choice you
  made immediately after the push is highlighted on the screen to show
  you the (presumably incorrect) choice you made last time.
- There is an undo statement, you can unwind operations back to the
  last push.
- If an entry you make conflicts with entries already on the board,
  the conflicting entries will be highlighted.  Note that this does
  not simply mark incorrect guesses, it marks guesses inconsistent
  with things already displayed, which could indicate that the current
  choice is wrong, but it could mean that an earlier mistake is
  responsible for the conflict.


You should compile "generate.lisp" to get things running at a
reasonable speed, but the "interactive.lisp" program is not CPU-bound.

The "screen-puzzle" function takes an optional argument.  If non-nil,
the program will generate and discard puzzles until it produces one
with a difficulty rating of "MEDIUM".

If anybody wants to write a CLX or mcclim interface, please go ahead,
the code in "interactive.lisp" should give all the hints you need.  In
particular, if I've made the interfaces sufficiently general, it
should be sufficient simply to write replacements for everything in
the block containing my defmethod()s.  If you care to share your
interfaces with others, please forward them to me so that I can
package them up and include them in later releases.

In principle, you could wrap a C++, Java, Perl etc. interface around
this.  Just run the lisp puzzle generator in a sub-process.  For
instance,

popen("clisp -q -i generate -x '(number-puzzle:make-puzzle) (format t \"~S~%~%~S~%\" (number-puzzle:show-puzzle) (number-puzzle:show-solution))'")

will produce a stream of data which, properly parsed, can be used by
your own specialized interactive code.




-----------------

GPL-ed, with all that that entails.

Email comments to 
(delete-if #'digit-char-p "s1u2d3o9k8u7-puzzle44455@cneufeld.ca")