xd-crossword-tools

xd is a text-based crossword format which is easy for humans to read and reason about.

This repo provides tools for taking different crossword file formats and converting them to xd. Then has a comprehensive xd to JSON function. Mostly conforms to the v2 xd spec, and comes with a few editor-experience extensions for a REPL-like environment. Uses a vendored copy of 'puzjs' which was ported to TypeScript.

Runs in node, browsers, React Native and edge runtimes.

Documentation for authoring in xd

User Guide.

.xd to .JSON

import { xdToJSON } from "xd-crossword-tools"

const xd = "[...]"
const crossword = xdToJSON(xd)

The JSON format is a bit more verbose than you might expect (see below for an example), but the goal is to have as much information pre-computed at parse time in order to save lookups later at runtime. You should use crossword.report to determine the parsing's success. You can see the type definitions here: ./lib/types.ts.

.puz to .xd

Builds on puzjs (ISC license). The puz format is generally what tools and websites will give you as an output format.

import { puzToXD } from "xd-crossword-tools"

const puzResponse = await fetch(url)
const puzBuffer = await res.arrayBuffer()
const xd = puzToXD(puzBuffer)

This API should cover most features in puz and xd.

UClick .xml to .xd

import { uclickXMLToXd } from "xd-crossword-tools"

const xmlResponse = await fetch(url)
const xmlString = await res.body()
const xd = uclickXMLToXd(xmlString)

.xd to .puz

We don't support all of .puz features, but this library can generate a JSON object which can then be used @confuzzle/writepuz to generate a .puz file as a buffer which you can write to a file in node, or offer as a download on the web.

import { JSONToPuzJSON } from "xd-crossword-tools"
import { writepuz } from "@confuzzle/writepuz"

const xd = "[...]"
const writeJSON = JSONToPuzJSON(xd)
const puzBuffer = writepuz(writeJSON)

Editor Support

You can opt-in to more information from the parser, and lint warnings, by passing true as the third argument to xdToJSON.

Triggering this will:

• Turn on the linter for your code editor, which will give you warnings about your crossword based on pretty universally useful rules.
• Add section metadata in the return value's editorInfo property
• Add line numbers to the metadata section of the puzzle
• Add line numbers to clues/hints/other in the metadata section of each clue

This library includes editorInfoAtCursor which can get some information about what's under the cursor at { line, index }.

import { xdToJSON, editorInfoAtCursor } from "xd-crossword-tools"

const xd = "[...]"
const editorSupport = true
const crossword = xdToJSON(xd, true, editorSupport)

const info = editorInfoAtCursor(crossword)
const cursorInfo = info(0, 0)

Which returns a union of different results, you can check the types + tests to see what's available, but it's something like this:

export type PositionInfo =
  | { type: "noop" }
  | { type: "grid"; position: Position }
  | { type: "clue"; direction: CursorDirection; number: number }
  | ...

xd Diffing

This library includes a diffing function which can take two xd strings and return a list of changes. This is useful for version control, and for building a diffing UI.

import { diffXD } from "xd-crossword-tools"

const diff = diffXD(xd1, xd2)

Example

Let's take this free .puz: https://dehodson.github.io/crossword-puzzles/crosswords/alpha-bits/

Their .puz file turns into this xd:

## Metadata

title: Alpha-Bits
author: Drew Hodson
copyright: © 2021
description: N/A

## Grid

AHAB..CUD.SERIF
MADAM.ANY.ABODE
PLANE.DIE.NOTON
....TODO.EGO...
GASH.NINJA.KEEL
ARTICLE.ORU.DOE
YEARLY.MISPRINT
..NEI.MAN.SOT..
CALENDAR.RETIES
ICE.TAR.POTHOLE
OTEP.HQTRS.SNIT
...ALL.HEAL....
SPIRO.NET.ATLAS
TARTS.ETA.DOONE
UWAVE.WAX..YUTZ

## Clues

A1. Captain of the Pequod ~ AHAB
A5. Food for second chance chewing ~ CUD
A8. Font feature ~ SERIF
A13. Palindromic address to a female ~ MADAM
A15. ___ Way You Want It ~ ANY
A16. Place often described as humble ~ ABODE
A17. Flat two dimensional surface in geometry ~ PLANE
A18. Grim homophone of 7D ~ DIE
A19. Off ~ NOTON
A20. Heading for some lists ~ TODO
A22. Kanye West is famous for his ~ EGO
A23. Laceration ~ GASH
A27. Alias of Twitch star Richard Tyler Blevins ~ NINJA
A29. Capsize ~ KEEL
A33. Piece of clothing or print ~ ARTICLE
A35. Evangelical school in Tulsa, OK ~ ORU
A37. ___-eyed ~ DOE
A38. Annual ~ YEARLY
A39. The stamp with the upside down airplane is a famous one ~ MISPRINT
A41. With 42A and Marcus, a luxury department store chain ~ NEI
A42. 41A continued ~ MAN
A43. Lush ~ SOT
A44. The Mayan one ended in 2012 ~ CALENDAR
A47. What a child often does to their shoes ~ RETIES
A50. Vanilla ___ ~ ICE
A51. Maligned cigarette ingredient ~ TAR
A52. Frequent cause for a new tire ~ POTHOLE
A53. Los Angeles heavy metal act ~ OTEP
A55. Bldgs. such as the Googleplex ~ HQTRS
A57. A fit of irritation ~ SNIT
A58. Lead-in to American or day ~ ALL
A60. What Pokémon do at a Pokémon Center ~ HEAL
A62. Nixon's vice ~ SPIRO
A65. Nothing but ___ ~ NET
A66. One with the world on his shoulders ~ ATLAS
A71. Filled pastries ~ TARTS
A72. Age, in Milan ~ ETA
A73. Lorna ___, novel or cookie ~ DOONE
A74. Electrocardiogram readout feature ~ UWAVE
A75. Hip slang for records ~ WAX
A76. Yiddish for a foolish person ~ YUTZ

D1. Pc. of concert gear ~ AMP
D2. AI antagonist of 2001 ~ HAL
D3. Programming pioneer Lovelace ~ ADA
D4. Prohibit ~ BAN
D5. Type of person to routinely carry a club ~ CADDIE
D6. State of the ___ Address ~ UNION
D7. Colorful homophone of 18A ~ DYE
D8. Snitched ~ SANG
D9. Kindle fare ~ EBOOK
D10. Decayed matter ~ ROT
D11. Type of response you hope to get at the altar ~ IDO
D12. Peat-accumulating wetland ~ FEN
D14. The ___, NY art museum ~ MET
D21. ___Fans ~ ONLY
D22. Friends, Romans, countrymen, lend me your... ~ EARS
D23. "Friend of Dorothy" ~ GAY
D24. We ___ the Champions ~ ARE
D25. Father of Spider-Man ~ STANLEE
D26. What a certain applicant becomes ~ HIREE
D28. Connect ~ JOIN
D30. Particular form of a published text ~ EDITION
D31. Suffix at the end of all of Eevee's evolutions ~ EON
D32. Live and ___ Die ~ LET
D34. Famous Eastwood whose name became a famous Gorillaz song ~ CLINT
D36. Unexpected result in a sporting competition ~ UPSET
D39. Disfigure ~ MAR
D40. David Lee and Tim ~ ROTHS
D42. Luxury watch collection by Garmin ~ MARQ
D44. Top dog in an IT org ~ CIO
D45. Sister ___ ~ ACT
D46. Author Roald ~ DAHL
D47. Civil rights activist Parks ~ ROSA
D48. An additional name that could be part of 40D's clue ~ ELI
D49. Director's domain ~ SET
D52. Type of income to go in a 401k ~ PRETAX
D54. The Empire Strikes Back, to the Star Wars saga ~ PARTV
D56. Greek letter following 72A ~ THETA
D59. Misplace ~ LOSE
D61. Wee boy ~ LAD
D62. Dad to Tommy Pickles ~ STU
D63. The only Patrol I trust ~ PAW
D64. Smart savings plan, briefly ~ IRA
D65. Fresh ~ NEW
D67. Breeds such as Chihuahua or Pomeranian ~ TOY
D68. Bega behind "Mambo No. 5" ~ LOU
D69. Aardvark breakfast ~ ANT
D70. Sonic ___ ~ SEZ

## Notes

## Design

<style>O { background: circle }</style>

O..O##O.O#.O..O
.....#...#.....
.....#...#.....
####....#...###
O..O#.O.O.#O..O
.......#...#...
......#........
##...#O.O#...##
........#......
...#...#.......
O..O#.O.O.#O..O
###...#....####
.....#...#.....
.....#...#.....
O..O.#O.O##O..O

xd Extensions

This lib creates xd compatible files, but also extends the format in a way that allows for thinking of xd as a human-editor format.

Structural

• Headers - xd out of the box has an implicit order:

  • Meta
  • Grid
  • Clues
  • Notes (optional)

  This library respects that behavior, but also supports a markdown header format whereby you could write an xd document like:

  ## Metadata
  
  Title: Square
  Author: Orta
  Editor: Orta Therox
  Date: 2021-03-16
  
  ## Grid
  
  BULB
  OK#O
  L##O
  DESK
  
  ## Clues
  
  A1. Gardener's concern. ~ BULB
  A4. A reasonable statement. ~ OK
  A5. The office centerpiece. ~ DESK
  
  D1. To \_ly go. ~ BOLD
  D2. Bigger than britain. ~ UK
  D3. A conscious tree. ~ BOOK

  This makes the sections a bit more explicit (and conceptually more user-friendly if you have not read the xd documentation ahead of seeing the file) and frees the order in which someone could write a document. Capitalization is ignored.

• Clue Metadata

  You can add arbitrary metadata to clues by repeating the clue with a custom suffix:

  A1. Gardener's concerns with A2 and D4. ~ BULB
  A1 ^Hint: Turned on to illuminate a room.
  A1 ^Refs: A2 D4
  
  A4. A reasonable statement. ~ OK
  A4 ^Hint: All \_\_.
  
  A5. The office centerpiece. ~ DESK
  A5 ^Hint: Fried.
  
  D1. To \_ly go. ~ BOLD
  D1 ^Hint: When you want to make some text stronger.
  
  D2. Bigger than britain. ~ UK
  D2 ^Hint: A union which left europe.
  
  D3. A conscious tree. ~ BOOK
  D3 ^Hint: Registering with a restaurant. ~ BOOK

  Capitalization is ignored, the metadata prefix will always be given as lowercase inside the JSON representation.

• Markdown/HTML style comments

  In markdown you can write <!-- and --> to comment out a section of your code. Our implementation is not super smart:

  ## Metadata
  
  <!--  WIP: Maybe it should be called rectangle? -->
  
  Title: Square
  Author: Orta
  Editor: Orta Therox
  
  <!--
  Date: 2021-03-16
  -->

  The key is that a line has to start with <!-- and eventually the same or another line has to end with -->.

• Markdown clue syntax

When a clue is written in markdown, it will be parsed into a JSON representation that can be used to render the clue in a UI. The markdown syntax is limited, but should be enough to cover most cases. The syntax is:

A1. [Captain](https://github.com/orta) _of_ /the/ ship Pequod ~ AHAB

Which will add the optional "bodyMD" to the clue:

{
  "answer": "AHAB",
  "body": "[Captain](https://github.com/orta) *of* /the/ ship Pequod",
  "bodyMD": [
    ["link", "Captain", "https://github.com/orta"],
    ["text", " "],
    ["bold", "of"],
    ["text", " "],
    ["italics", "the"],
    ["text", " ship Pequod"]
  ]
}

• Italics /word/ or /a phrase/ (not _word_ because _ is often used as a "gap" in the clue text)

• Bold: *word* or *a phrase*

• Strike through: ~word~ or ~a phrase~

• Link: [text](url)

• Split character

  Provide hints for where one word terminates and the next begins in a single solution by declaring SplitCharacter: {character} in Metadata, and adding the chosen SplitCharacter between words in Clues.

  ## Metadata
  SplitCharacter: |
  
  ## Clues
  …
  D25. Father of Spider-Man ~ STAN|LEE

  The 'answer' given from the parser here will be 'STANLEE', but the indexes for each bar will be noted in the clue.

Spec-Breaking Differences

We want to highlight that 'Clue Metadata', 'Comments' and 'Split Characters' are all spec-breaking extensions. E.g. a parser which conforms exactly to the xd spec would likely choke when seeing these features.

We'd be open to a variant of our JSONToXD function which produces spec-compliant versions of the xd files instead of just our extensions.

Metadata

• Shrodinger's Squares. It's likely that a special form of Rebus will work here, for example:

  Rebus: 1=M|F

  Indicates to the game engine that the rebus for 1 on the grid can be either M or F.

  Rebus: 1=M&F 2=L&T

  Indicates to the game engine that the rebus for 1 on the grid can be either M or F, but that the side needs to be respected across all possible rebuses in the clue. So for M1L2 you could have MALE and FATEbut not FALE or MATE.

Notes

• ## Design

  This is our WIP extension to describe the visual aspects of individual cells. The xd format uses lowercase letters in the grid to indicate a particular special trait (for example having a circle background.) We are looking at describing a more complex set of visual attributes, and so the puz -> xd parser uses a new section to indicate the design attributes in a manner similar to how rebuses are handled.

  ## Design
  
  <style>
  O { background: circle }
  </style>
  
  ....###...#....
  ....##....#....
  ....#.....#....
  ............###
  ...#....##....#
  ......#....O...
  ##...#....#O...
  ..O....#...O...
  ..O.#....#.O.##
  ..O.....#..O...
  #.OO.##....#O..
  ###O........O..
  ...O#.....#.O..
  ...O#....##.O..
  ...O#...###.O..

• ## Start

  Instead of starting with an board, create a board with letters pre-filled. For example this crossword would start with "GO" "FOR" and "IT" already in:

  ## Start
  
  GO..##FOR#IT...
  .....#...#.....
  .....#...#.....
  ####....#...###
  ....#.....#....
  .......#...#...
  ......#........
  ##...#...#...##
  ........#......
  ...#...#.......
  ....#.....#....
  ###...#....####
  .....#...#.....
  .....#...#.....
  .....#...##....

• ## Metapuzzle

  We'd like a way to describe a final question and a final answer for a puzzle. For example, in alpha-bits above the circles indicate a letter pattern and there could be a way to respond that you got the theme. For example:

  ## Metapuzzle
  
  How are the words sorted?
  
  > Alphabetic

  Case in the answer should be ignored by engines.

Filetypes this lib is open to adding

• http://www.ipuz.org
• https://www.xwordinfo.com/XPF/ / https://www.xwordinfo.com/JSON/