     __  __             _        ____                             
    |  \/  | __ _  __ _(_) ___  / ___|  __ _ _   _  __ _ _ __ ___ 
    | |\/| |/ _` |/ _` | |/ __| \___ \ / _` | | | |/ _` | '__/ _ \
    | |  | | (_| | (_| | | (__   ___) | (_| | |_| | (_| | | |  __/
    |_|  |_|\__,_|\__, |_|\___| |____/ \__, |\__,_|\__,_|_|  \___|
                  |___/                   |_|                     


"They call them 'squares' because it's the most complicated shape they
can deal with."
		-- fortune(6)

======================================================================


Introduction to Magic Squares
=============================

Magic squares are squares of numbers for which all of the rows,
columns, and center diagonals add up to the same amount. For example,
take the following magic square:

  +--+--+--+
  |2 |7 |6 |
  +--+--+--+
  |9 |5 |1 |
  +--+--+--+
  |4 |3 |8 |
  +--+--+--+

Note that all of the rows ((2 + 7 + 6), (9 + 5 + 1), (4 + 3 + 8)), the
columns ((2 + 9 + 4), (7 + 5 + 3), (6 + 1 + 8)), and the center
diagonals ((2 + 5 + 8), (6 + 5 + 4)) all add up to 15. If they didn't,
it wouldn't be a magic square.

Now, take an incomplete magic square (the numbers which the blank
spaces can be filled with are listed below the square):

  +--+--+--+
  |  |  |6 |
  +--+--+--+
  |9 |  |1 |
  +--+--+--+
  |4 |  |  |
  +--+--+--+

  (2, 3, 5, 7, 8)

Is there a solution to this? (If you'd like to try to solve it
yourself, stop reading here.)

If you look carefully, you will notice that it is simply the first
magic square we saw with some numbers removed. That happens to be the
only solution for that magic square.


Installing
==========

Magic Square does not depend on any libraries (aside from libc). As
long as you have a decent C compiler,

  $ ./configure && make && sudo make install

should do the trick.

See the file INSTALL for more information.


Format
======

The format for magic squares inputted to the `square' program is very
simple. In fact, you've already seen it!

Squares are defined with cells separated with '|' and '-' at the sides
and '+' at the corners. The cells can be any width and height, as long
as they are consistent (and greater than zero). If there are any empty
cells, they must be specified below the square in parentheses. For
example:

  +------+------+
  | 1000 |0.1234|
  |      | 5678 |
  +------+------+
  |0xdead|      |
  |beefp5|      |
  +------+------+

  (6.022e23)

Optionally, a description may be prepended to the square. For example:

  This is an empty 4x4 magic square.

  +-+-+-+-+
  | | | | |
  +-+-+-+-+
  | | | | |
  +-+-+-+-+
  | | | | |
  +-+-+-+-+
  | | | | |
  +-+-+-+-+

  (1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16)

If you run the `square' program on it, you will get:

  This is an empty 4x4 magic square.

  +--+--+--+--+
  |1 |12|13|8 |
  +--+--+--+--+
  |16|9 |4 |5 |
  +--+--+--+--+
  |2 |7 |14|11|
  +--+--+--+--+
  |15|6 |3 |10|
  +--+--+--+--+

(Although, of course, it is no longer empty).

The numbers in parentheses can either be all of the numbers in the
square or only the numbers that would fill in the blanks spaces. For
example:

  +--+--+--+
  |  |7 |6 |
  +--+--+--+
  |  |  |1 |
  +--+--+--+
  |  |  |  |
  +--+--+--+

  (2, 3, 4, 5, 8, 9)

and

  +--+--+--+
  |  |7 |6 |
  +--+--+--+
  |  |  |1 |
  +--+--+--+
  |  |  |  |
  +--+--+--+

  (1, 2, 3, 4, 5, 6, 7, 8, 9)

are equivalent.

All syntax errors will be considered part of the description. This may
not be desirable in some cases, and may be changed in the future.


Usage
=====

You've already seen how to find one solution for a magic square, but
suppose you want to find ALL the solutions. For example, suppose you
have the following square in the file `test.square':

  +--+--+--+--+
  |1 |  |  |  |
  +--+--+--+--+
  |  |  |10|  |
  +--+--+--+--+
  |  |3 |  |  |
  +--+--+--+--+
  |  |  |  |  |
  +--+--+--+--+

  (1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16)

Now look at the following commands:

  $ square test.square
  +--+--+--+--+
  |1 |14|11|8 |
  +--+--+--+--+
  |4 |15|10|5 |
  +--+--+--+--+
  |16|3 |6 |9 |
  +--+--+--+--+
  |13|2 |7 |12|
  +--+--+--+--+
  $ square -k test.square
  Solution 1:

  +--+--+--+--+
  |1 |14|11|8 |
  +--+--+--+--+
  |4 |15|10|5 |
  +--+--+--+--+
  |16|3 |6 |9 |
  +--+--+--+--+
  |13|2 |7 |12|
  +--+--+--+--+

  Solution 2:

  +--+--+--+--+
  |1 |16|11|6 |
  +--+--+--+--+
  |4 |13|10|7 |
  +--+--+--+--+
  |14|3 |8 |9 |
  +--+--+--+--+
  |15|2 |5 |12|
  +--+--+--+--+

  Solution 3:

  +--+--+--+--+
  |1 |14|4 |15|
  +--+--+--+--+
  |11|8 |10|5 |
  +--+--+--+--+
  |16|3 |13|2 |
  +--+--+--+--+
  |6 |9 |7 |12|
  +--+--+--+--+

  Solution 4:

  +--+--+--+--+
  |1 |16|4 |13|
  +--+--+--+--+
  |11|6 |10|7 |
  +--+--+--+--+
  |14|3 |15|2 |
  +--+--+--+--+
  |8 |9 |5 |12|
  +--+--+--+--+

By default, `square' only prints the first solution found. But with
the "-k, --keep-going" option, it prints all the solutions.

You can also compile to a binary format with `squarec'. Run

  $ squarec --help

for more info. `square' can also read the binary format compiled with
`squarec'. Run

  $ square --help

for more info.



======================================================================

Copyright (C) 2019  Asher Gordon <AsDaGo@posteo.net>

Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved.  This file is offered as-is,
without any warranty.
