I was trying to parse some XML. The only documentation for Foundation that I can see is Apple’s hosted documentation. Searching there revealed XMLParser, which looked like what I wanted.
However, when I tried to use it I got errors along the lines of error: 'XMLParser' (aka 'AnyObject') cannot be constructed because it has no accessible initializers. After some poking about, I discovered that XML parsing was split into FoundationXML. I’m working in Windows at the moment so this leads to several questions (do I have to import FoundationXML on Darwin? On Linux?) but my real question is this:
Apple’s documentation doesn’t mention this at all – I suspect because it’s not needed, but I haven’t tried on a Mac to confirm yet. If the Foundation that we use on Windows is subtly (and not so subtly) different to the Foundation used on Linux, used on Darwin, how is a programmer on those platforms who might not have seen these forum topics supposed to discover this stuff? Is there a more generic Foundation documentation source that I’m missing?
Neither swift-foundation or swift-corelibs-foundations’ GitHub pages mention anything about documentation. The swift.org website only links to Apple’s documentation. Things like which version of Swift something is usable from is also missing, instead being defined entirely in Apple OS release versions.
I was about to post a link to SwiftPackageIndex which has documentation for FoundationEssentials, but you’re right - FoundationXML (and FoundationNetworking) don’t have any documentation anywhere. You’re right it’s a serious problem and needs to be fixed
You could try SwiftXML (although if you need to perform validation against a schema, you will need to use something like Libxml2Validation for now). This package is well documented and used e.g. by the German Institute for Standardisation.
Also be aware that FoundationXML has some issues with entities that do not occur with the mentioned package.
@sspringer,@rauhul thank you for the recommendations for XML parsing libraries! I might check them out. (Incidentally, I feel like I’ve used several languages with a ‘built in’ XML parser and the immediate community response to someone using them is “you probably don’t want to use that”)
@0xTim thanks for pointing me at SwiftPackageIndex. The multiple “levels” of foundation make the question more complicated.
In this case it looks like XMLParser lives under swift-corelibs-foundation, and not swift-foundation. Looking on SPI, swift-corelibs-foundation has no documentation linked, and the GitHub page has a README that doesn’t mention the word ‘documentation’, and in documentation issues people tend to link the Apple documentation (which as I understand it, is for the closed source Foundation only shipped on Apple platforms?)
I’m stubborn enough to work through these things, but I do worry that the pain point will turn newcomers away.
Yes, but nothing solid that I can announce at this point.
We definitely recognize this gap and want to improve the situation for both the standard library and the various elements that make up Foundation as it's compiled for linux (and other platforms) with their associated open-source toolchains.