#1032 Move json to util to match csv API

tactics Sun 21 Mar 2010

Brian added CsvIn/OutStream to the util pod the repo yesterday. It got me thinking about CSV vs. JSON in Fantom and about when a set of classes deserve its own pod.

The Json class contains two static methods and it gets its own pod.

The csv classes have a larger API and, of course, require two classes. But they get tossed into util.

I think to keep things consistent, either csv should be given its own pod or Json should be demoted to a utility class.

brian Sun 21 Mar 2010

Definitely a good point, and I'm not there is any clear cut answer to when something deserves its own pod.

The way I look at this problem is less about current surface area of the API, but more about:

  • complexity of implementation (one public API might have dozens of helper classes)
  • future expansion of the API

So is json like csv or more like xml?

CSV is cleanly implemented in only two classes, and highly likely its API will get any bigger (at least in terms of new classes).

XML is definitely sophisticated enough to warrant its own pod, and already has oodles of classes with high cohesion. And we'll definitely be expanding it in the future for XPath, etc.

Json, I'm not sure about. It sort of sits in a murky space between those two worlds. Eventually, we will likely want to expand the API to be more stream based with a JsonOutStream and JsonInStream. Would we ever want additional functionality in that pod like type based serialization? Or XPath like functionality?

My gut feel is still that csv is too small for its own pod, and that json deserves its own pod. But its definitely a good thing to question and think thru, especially if we can arrive at some good guidelines for modularity.

jodastephen Mon 22 Mar 2010

My gut feel is that csv should be separate. Otherwise core will bloat.

andy Mon 22 Mar 2010

My vote would be to replace Json with JsonInStream and JsonOutStream and move into util pod. Adding type-based serialization seems like it would just be a flag on those classes - and I don't think the API needs to expand beyond that.

I would also consider moving Json into web - since I would have to imagine the 99% case is you're using it with a webapp.

tactics Mon 22 Mar 2010

I would also consider moving Json into web - since I would have to imagine the 99% case is you're using it with a webapp.

I don't really like the sound of that. It's like putting CSV in the sql pod because most of the time my CSV files end up in the database.

I do like the idea of turning Json into stream classes, though. Fantom is very streamy.

msl Mon 22 Mar 2010

I'd be tempted to have a text pod for JSON/CSV, but that does create a pretty large punk elephant in the form of XML

KevinKelley Mon 22 Mar 2010

Boatloads of tiny pods doesn't seem good; packaging things in cohesive groups is better. Json's mostly going to be used by apps that are web-related, probably... but not necessarily always in the same parts that use the web pod. I'm thinking for example that you might want to store json to a db, say, use it as your frozen object format, so maybe you'd be handling json objects in places other than the web handlers.

So anyway I can see putting it in util, but in web doesn't seem bad either. Not a big fan of having it in its own pod.

brian Tue 23 Mar 2010

Json doesn't really have anything to do with web - its a serialization format like CSV XML, YAML, etc.

I don't really have a strong preference, if everybody wants to move it into util and we put the simple text parsers like CSV, JSON, YAML, etc there.

As a technique I'm been using FooInStream if the reader subclasses directly from InStream and exposes direct I/O access. Or FooReader if it wraps the input stream and hides direct access. It looks like JsonParser is more in the reader camp, but since it only reads ahead two chars might work ok as stream based.

Any other further suggestions for moving json APIs to util or other options?

tactics Tue 23 Mar 2010

One more idle suggestion. Since these are all serialization formats, why not have a seralization pod? That gives us a clear place for any other formats that show up in the core later on, such as BSON, YAML, or various property list dialects like Window's conf/ini files.

brian Tue 23 Mar 2010

Serialization doesn't strike me as quite right name. I'd probably lean more towards text or formats something. Although I think I still prefer just lumping this stuff into util.

tactics Tue 23 Mar 2010

Yeah, the name could be better. I just thought I'd toss out that last idea.

brian Wed 24 Mar 2010

Promoted to ticket #1032 and assigned to brian

brian Wed 24 Mar 2010

Renamed from CSV and JSON in the standard library to Move json to util to match csv API

brian Wed 24 Mar 2010

Ticket resolved in 1.0.52

The json::Json API is now replaced by util::JsonInStream and util::JsonOutStream.

The old API will remain in place for 1.0.52 as deprecated, and removed for build 1.0.53.

brian Mon 15 Nov 2010

I noticed some comments on IRC - I forgot to mention this in build notes, but I have removed the old json pod. It has been deprecated for most of the year now, so hopefully everyone has replaced their code with the util classes.

Login or Signup to reply.