Add the Format API

[mickael-menu]

Implementation of the Format API proposal.

It's quite a lot of code because I had to integrate ZIP and XML third-party libs in R2Shared and adapt DocumentTypes to be a bit more useful. Here's a few shortcuts to jump directly to the interesting types:

• MediaType
• Format
• Format.Sniffer
• FormatSnifferContext

Compared to the existing solution in the Swift toolkit, this new API offers:

• a centralized place for everything related to formats, it was a bit spread out
• content sniffing to detect a format when you only have a file (or bytes) without extension nor media type
• we can now differentiate various JSON-based formats
• extensibility for custom formats provided by reading apps
• handling edge cases with media types comparisons, simple equality check is not enough since they can have parameters in different order and they are case-sensitive only for the parameter values

You can see how this new API looks in practice in:

• Test App
• R2Streamer
• R2LCPClient

The original Format API proposal is extended a bit to take advantage of iOS capabilities. The sniffing algorithm is going through the provided sniffers, but if no known Format is found, then it falls back on two sources, in order:

1. The document types declared in the Info.plist, to automatically detect custom formats supported by the reading app without needing custom sniffers.
2. The system-wide UTIs, to detect any kind of known format. For example, it would work to detect a .xlsx file by returning the following Format generated from system-provided metadata:

Format(
    name: "Office Open XML spreadsheet",
    mediaType: MediaType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"),
    fileExtension: "xlsx"
)

A few notes about the implementation:

• The format detection is fully covered by a unit test suite.
• To support content sniffing with ZIP and XML, I had to integrate the Minizip and Fuzi third-party libraries. They are not new dependencies per se because they were used in R2Streamer, but now R2Shared has a Cartfile.
• I added two wrapper APIs: XMLDocument and ZIPArchive to avoid referring directly to third-party dependencies throughout the project, this has several advantages:
  • We'll be able to remove the dependencies in the other projects, since they will be able to use the ones provided by R2Shared.
  • It will be painless to swap dependencies for other third-party libs, since it's only referenced in one file. For ZIP, I already have an implementation for Minizip and ZIPFoundation (which is used in R2LCPClient).
  • We can have a generic test suite for libs implementing these interfaces, which allows to compare them and do benchmarking. Here's an example with ZIP. Having such test suites also provides an automated way to check that a third-party lib is still working as expected after upgrading it.
  • This opens the possibility of using XML/ZIP dependencies provided by reading apps.