Future API Requests or Suggestions

[drmohundro]

Because Swift 3.0 will be releasing soon, I'll also have to release a new and breaking version of SWXMLHash that will be versioned as 3.0.0 (in keeping with semantic versioning).

So... this seems as good a time as any to elicit feedback regarding improvements, suggestions, etc. particularly related to potential changes in the public API. I don't want to go nuts, but I'm open to improvements.

Some API-related thoughts I've had or gathered from other issues:

• Choose one way to access attributes
  • See Add XMLAttribute type w/ text deserialization #81 which deprecates the existing attributes collection anyway
  • This also introduces an actual type to encapsulate attributes (XMLAttribute) such that there would be an extension point for things like type conversion versus hanging extensions off of String
• Make children properties consistent
  • See make XMLElement children property public #83 which made the children property on XMLElement public because the children property of XMLIndexer didn't return TextElements.
• Consider changing XMLElement and TextElement to be enums
  • This might make accessing them somewhat more straightforward
  • Also suggested in make XMLElement children property public #83
• Consider consolidating more of XMLElement, etc. in XMLIndexer
  • This might make the API more discoverable versus having to call into element first

In addition, there is the feature request to support XPath at #9... I don't necessarily see this making it in time for 3.0 as I haven't even looked at it yet 😄

[DanielAsher]

@drmohundro: this looks really good. I'm very pleased that XPath support has made it onto this list. XPath is extremely versatile and would greatly enhance the power of this library!

[drmohundro]

@DanielAsher well, as I said, I haven't even started on it. I won't rule it out completely, but it is good to know that there is interest - knowing that helps me know which things to prioritize :)

[drmohundro]

FYI, I thought about this quite a bit and decided that it made more sense to have a separate API-breaking release than doing it along side Swift 3.0. My thought process was basically - everyone is already doing a lot of source changes. It will be easier on them if they don't have to chase down API changes on top of language changes.

(I'm probably a little too conservative with breaking changes... hope everyone can be patient with me!)

[useitsoftware]

suggestion: could .value() return a valid empty value if the node doesn't have a value for the next API update? for example -> '' / 0

im currently using .element.text to avoid exceptions.

[drmohundro]

@useitsoftware I like the idea... I'm certainly a fan of not throwing exceptions all the time and some XML can be inconsistent. I'm not sure if the behavior should totally change or if a new config should be added (e.g. strictParsing or something that would indicate if it blows up or returns default values). Thoughts?

[gca3020]

What about extending the value() function to include an optional withDefault param. Since what I think the default should be and what someone else thinks the default should be are likely different. And I can think of cases in the same XML where I want different defaults (especially on things like booleans)

For example:

myFloat = currentNode.value(withDefault: -1.0)

If I don't supply the withDefault param it will behave exactly like it does today and generate an exception if the xml is invalid. If I do, it will quietly return the value I specify.

[drmohundro]

👍 good thought @gca3020 - I like that a lot.

[drmohundro]

FYI, (once again), some of the above features did not make it into 4.0.0 - I'm still interested in working on them or looking at them, but I guess keeping up with the language and usage is my top priority.

I did try spiking out some of the code around merging XMLIndexer and XMLElement and I just couldn't really see how that would work well... I might be too blind to my prior design. I do think there is some sense in making XMLElement, TextElement, etc. be enums versus inheriting from a protocol - I'd want to spike out what the code would look like, though.

Outside of that, I can't see why adding a withDefault couldn't go in a 4.1 or 4.2 release... aside from me getting around to adding it anyway.

[ajsnow]

Small suggestion: public func byKey(_ key: String) throws -> XMLIndexer throws an IndexingError but one can build a valid XMLIndexer instance from that (case xmlError(IndexingError)) and the subscript method which calls byKey() does exactly that. If byKey() was changed to always return a XMLIndexer, that would cut down substantially on the number of spurious throws that clog Xcode's "Break on Swift Error."

[transat]

Are there any plans to be able to write to XML? Cheers.

[drmohundro]

Hi @transat - likely not any time soon. I wouldn't be opposed to adding that functionality, but there'd have to be a significant effort in terms of coming up with a good API design that feels natural. I can think about what it would look like to support changing individual elements at an index level, but I don't know about building a completely new XML document. The serialization support would probably be the best, but I'd want to ensure that serialization wasn't required.