Error Handling in libipuz
Error Handling in libipuz
libipuz reports three kinds of problems with a puzzle:
- Fatal Errors: No puzzle can be built. Loading returns
NULLand sets aGError. - Dropped Data: The puzzle loaded, but some of the file couldn’t be used.
- Puzzle Problems: The puzzle is valid, but something about it may need attention, such as a clue with no text.
Fatal Errors
Fatal Errors only occur when loading a puzzle.
If the file or stream can’t be read, you get the error from GLib
unchanged. It will be GFileError when loading a file, or
GIOErrorEnum when loading a stream. All other fatal errors
are in the IpuzPuzzleError domain, with these codes, listed
in the order a loader might hit them:
| Code | Meaning |
|---|---|
INVALID_JSON |
The file isn’t valid JSON |
INVALID_FILE |
Valid JSON, but not an ipuz file |
WRONG_VERSION |
The file is an ipuz version we don’t support |
UNSUPPORTED_KIND |
The file is a puzzle kind we don’t support |
INVALID_STRUCTURE |
The file is missing something critical to build the puzzle |
INVALID_STRUCTURE is for files we can’t build a puzzle from at all,
such as a grid larger than IPUZ_GRID_MAX_SIZE.
Dropped Data
Dropped Data is used to indicate information that was in the file,
but isn’t in the loaded puzzle. It’s recorded as
IpuzPuzzleLoadFlags, read through
ipuz_puzzle_info_get_load_flags(). The flags describe the file
that was loaded, so they don’t change as the puzzle is edited. They
are copied by ipuz_puzzle_deep_copy(), but not compared by
ipuz_puzzle_equal().
| Flag | Cause |
|---|---|
GRID_TRUNCATED |
Cells beyond the grid’s dimensions were dropped |
CLUE_CELLS_DROPPED |
Clue cells outside the grid were dropped |
KIND_IGNORED |
An unsupported kind was ignored in favor of another |
VALUE_DROPPED |
A field had the wrong type, and was ignored |
Puzzle Problems
Puzzle Problems are calculated from the puzzle’s current state, so they apply to puzzles built through the API as well as loaded ones.
These are reported as IpuzPuzzleProblems, read through
ipuz_puzzle_info_get_problems(). A value of
IPUZ_PUZZLE_PROBLEM_NONE means there’s nothing to warn about.
These flags describe the puzzle as it is rather than indicate an error. They’re sometimes intentional in the puzzles and can be displayed/played anyway, in a degraded fashion. Some puzzles, such as alphabetic crosswords, do these things on purpose. Other puzzles may have no solution but a checksum. Applications should display the puzzle anyway, and decide how to present each problem.
| Flag | Cause |
|---|---|
NO_SOLUTION |
A guessable cell has no solution |
NOTHING_TO_GUESS |
There are no guessable cells |
EMPTY_CLUE_TEXT |
A clue has no text |
CLUE_WITHOUT_CELLS |
A clue has no cells |
CELL_WITHOUT_CLUE |
A guessable cell isn’t part of any clue |
A guessable cell is a normal cell without an initial value.
Note
Puzzle problems are separate from IpuzPuzzleFlags, which
describe what the puzzle contains. In particular,
IPUZ_PUZZLE_FLAG_HAS_SOLUTION means the loaded file had a
solution, and doesn’t change after loading.
IPUZ_PUZZLE_PROBLEM_NO_SOLUTION checks every guessable cell in
the current puzzle, so a puzzle can have both if its solution has gaps.