Extensions to the ipuz spec that we support

In general, we try to keep as close to the ipuz spec as possible. In some areas the spec is unclear or allows for interpretation. In other areas we want to extend it to get additional functionality. This document captures those differences.

Puzzle Types

Barred puzzles

We tag barred filippine puzzles as being a separate puzzle type through the https://libipuz.org/barred#1 kind tag. These are parseable as normal crosswords, and will also contain https://ipuz.org/crossword#1

Filippine puzzles

We tag dutch-style filippine puzzles as being a separate puzzle type through the https://libipuz.org/filippine#1 kind tag. These are parseable as normal crosswords, and will also contain https://ipuz.org/crossword#1

Style on BLOCKS

While this is often redundant to the solving of the puzzle, it’s nice stylistically. It lets us set a BLOCK to be a specific color rather than just black. It is recommended that implementations texture the block differently from a straight colored cells when this happens.

Example:

{"cell":"#", "style": {"color":"#ffff"}}

License

The license of the puzzle. We expect these to be a recognized string description of a well-known license, and not the full license text. The description should come from the SPDX License List when applicable. Otherwise, a URL is recommended for a custom or proprietary license.

Example:

  "org.libipuz:license": "CC-BY-SA-2.0"

Locale

Indicates the locale the puzzle is written for. This can be useful for filtering out the language of the puzzle for users that don’t speak the language. It should not affect the parsing of the puzzle at all. It is assumed that if a puzzle doesn’t have a language tag, it’s of the “C” Locale.

Example:

  "org.libipuz:locale": "nl_NL"

Charset List

The Charset list is a supplement for the charset variable. It’s supposed to be used to handle multi-character cell values. Ideally, the ipuz spec would accept both a long string as well as a list. Until the spec changes, we handle it as an extension

Example:

  "org.libipuz:charset": [ "A", "B", "C", ..., "P", "Q", "QU", "R", ..., "X", "Y", "Z" ]

HTML

We convert the HTML strings into something that’s appropriate for gmarkup. This is a subset of the valid html, though doesn’t include all entities. See Issue #16 for more details.

Cell coordinates

The spec refers to COL1 and ROW1 as a coordinate for a row but doesn’t explicitly indicate if it starts at 0 or 1? The first crossword example implies it starts at zero, but the spec has examples (such as Calcudoku) that imply the coordinates start at 1. * We interpret it as starting at 0, which is what some of the puzzles I’ve found in the wild use. * puzzaz interprets as 0-based as well, which is further indication we should use that.

Unclear ipuz spec items

  • What does clueplacement do?

  • What does annotation do?