Am 22.08.2014 18:15, schrieb "Marc Schütz" <[email protected]>":
Some thoughts about the API:
1) Instead of `parseJSONValue` and `lexJSON`, how about static methods
`JSON.parse` and `JSON.lex`, or even a module level functions
`std.data.json.parse` etc.? The "JSON" part of the name is redundant.
For those functions it may be acceptable, although I really dislike that
style, because it makes the code harder to read (what exactly does this
parse?) and the functions are rarely used, so that that typing that
additional "JSON" should be no issue at all. On the other hand, if you
always type "JSON.lex" it's more to type than just "lexJSON".
But for "[JSON]Value" it gets ugly really quick, because "Value"s are
such a common thing and quickly occur in multiple kinds in the same
source file.
2) Also, `parseJSONValue` and `parseJSONStream` probably don't need to
have different names. They can be distinguished by their parameter types.
Actually they take exactly the same parameters and just differ in their
return value. It would be more descriptive to name them parseAsJSONValue
and parseAsJSONStream - or maybe parseJSONAsValue or parseJSONToValue?
The current naming is somewhat modeled after std.conv's "to!T" and
"parse!T".
3) `toJSONString` shouldn't just take a boolean as flag for
pretty-printing. It should either use something like `Pretty.YES`, or
the function should be called `toPrettyJSONString` (I believe I have
seen this latter convention elsewhere).
We should also think about whether we can just call the functions
`toString` and `toPrettyString`. Alternatively, `toJSON` and
`toPrettyJSON` should be considered.
Agreed, a boolean isn't good for a public interface, renaming the
current writeAsString to private writeAsStringImpl and then adding
"(writeAs/to)[Pretty]String" sounds reasonable. Actually I've done it
that way for vibe.data.json.
