Metadata-Version: 2.4
Name: xdformat
Version: 0.2.0
Summary: The .xd plain-text crossword format: spec, parser, and converters
Author-email: Saul Pwanson <xd@saul.pw>
License-Expression: MIT
Project-URL: Homepage, https://github.com/century-arcade/xdformat
Project-URL: Repository, https://github.com/century-arcade/xdformat
Project-URL: Issues, https://github.com/century-arcade/xdformat/issues
Project-URL: Specification, https://github.com/century-arcade/xdformat/blob/master/doc/xd-format.md
Keywords: crossword,puzzles,xd,puz,ipuz
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Games/Entertainment :: Puzzle Games
Classifier: Topic :: Text Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: convert
Requires-Dist: puzpy>=0.2.6; extra == "convert"
Requires-Dist: ipuz; extra == "convert"
Dynamic: license-file

# xdformat

.xd is a plain-text format for crossword puzzles, modeled after the simplicity of markdown.  A complete puzzle -- metadata, grid, clues, answers, notes -- is one small UTF-8 file that can be read, edited, diffed, and grepped like any other text file:

    Title: New York Times, Saturday, January 1, 1955
    Author: Anthony Morse
    Editor: Margaret Farrar
    Rebus: 1=HEART 2=DIAMOND 3=SPADE 4=CLUB
    Date: 1955-01-01


    1ACHE#ADAM#2LIL
    BLUER#GULL#MATA
    EATIN#APEX#ICER
    [...]


    A1. Sadness. ~ HEARTACHE
    A6. Progenitor. ~ ADAM
    A10. Mae West stand-by. ~ DIAMONDLIL
    [...]

    D1. Vital throb. ~ HEARTBEAT
    D2. Having wings. ~ ALATE
    [...]

The format supports 99.99% of published crosswords and is intended to be convenient for bulk analysis by both humans and machines, from the present and into the future.

This repo holds the format specification and the reference tools for parsing .xd and converting other puzzle formats into it.

## The spec

- [doc/xd-format.md](doc/xd-format.md) -- the format specification (v3.0)
- [doc/xd-format-v4.md](doc/xd-format-v4.md) -- the v4.0 draft specification, still in discussion
- [doc/rebus-conventions.md](doc/rebus-conventions.md) -- rebus/quantum/Schrödinger conventions observed in the corpus (extensions to the spec, not yet formalized)
- [doc/character-encoding.md](doc/character-encoding.md) -- character-encoding oddities inherited from source formats, and how the converters clean them up

## The xdformat Python package

The core package parses and emits .xd with no dependencies:

    pip install xdformat

```python
import xdformat

xd = xdformat.parse("nyt1955-01-01.xd")
xd.get_header("Title")        # "New York Times, Saturday, January 1, 1955"
xd.grid                       # list of row strings
for pos, clue, answer in xd.iterclues():
    ...
print(xd.to_unicode())        # canonical .xd text
```

The converters need the `[convert]` extra (pulls in [puzpy](https://github.com/alexdej/puzpy) and [ipuz](https://pypi.org/project/ipuz/)):

    pip install xdformat[convert]

    puz2xd foo.puz > foo.xd
    puz2xd -o xd/ *.puz
    ipuz2xd bar.ipuz > bar.xd

`xdformat/crossword/` is a vendored fork of Simeon Visser's [crossword](https://github.com/svisser/crossword) library, updated for changes in the ipuz module.

## Related repos

- [century-arcade/xd](https://github.com/century-arcade/xd) -- the corpus pipeline: downloads puzzles from many sources, converts them (using additional publisher-specific converters), analyzes grids and clues, validates with `xdlint.py`, and builds the website at [xd.saul.pw](https://xd.saul.pw)
- gxd -- the corpus itself, 95k+ puzzles in .xd format (private; join [#crosswords on the Discord](https://saul.pw/chat) to discuss getting access)
- [century-arcade/xdcontrib](https://github.com/century-arcade/xdcontrib) -- deprecated; its minimal converters were merged into this repo

## Citing xd

If you publish any research or results using the xd crossword corpus, please cite xd accordingly:

    Pwanson, Saul. (2019). "xd Crossword Corpus." Retrieved from http://xd.saul.pw

The year of publication should be the year that the corpus was accessed.

## License

MIT; see [LICENSE](LICENSE).
