I'm about to make a few changes in some of my libraries and I'd like to ask the language devs a key question about the $ stringify operator. I want to make sure my libraries are following "nimish" convention as much as possible.
So, my question: what is the specific purpose of the operator in Nim and, more specifically, who is the intended audience for the generated string?
In the world of JSON and XML, the word "stringify" has a very specific meaning: converting the data structure to the string version of the spec. Essentially, if you "stringify" an XML document, you can turn around and "parse" that string and get the original data structure back (in full). Outside of that, I've only seen the term used for human grammar, which simply means a "textual representation" which can be a summary or a spelling or what-have-you.
If that is the intended meaning of $, then if you had a type called, for example, DoctoralThesis and I followed general Nim convention, then:
let a = newDoctoralThesis()
#
# add details to a, then...
#
let stringifiedA = $a
let recoveredA = parseDoctoralThesis(stringifiedA) # `recoveredA` should have the same content as `a`
would be expected to work.
I'm not saying everyone's implementation of $ follows this model. I've seen lots of examples that don't. :)
In fact, I've also seen it used in two other ways:
Generating a useful representative string of the type with a short summary of details. So, very useful to programmers and debugging.
DocThesis(Brown, 1995)
Generating an easily understood string equivalent. Very useful for creating output to be seen by end users. But, not reliably parsable.
Brown, C. (1995). Understanding and care of fictional beagles. Washington archives. (1445202-23)
but if it is meant to be parsable/reconstructable, the string could look something like:
("Brown", "C.", 1995, "Understanding and care of fictional beagles", "Washington archives", "1445202-23")
Anyway, sorry to ask such a pedantic question.
I'm happy to write a PR to the docs if the answer to this question is useful to others.