From: Jason D. <ja...@in...> - 2001-06-17 20:33:45
|
Hi. Recently, Oren posted an example that looked like this: my-machine: 192.168.1.17 Which was then modified to look like this: my-machine: %= =: 192.168.1.17 #: DON'T CHANGE THIS! several clients access this address directly - talk with the Network Administrator first. I think that this is an excellent example of why substitutability is important and why our APIs should support it. However, I think that introducing a comment construct into the language would be a mistake. Do we really need a special comment key? If we were going to allow people to mark up comments using indicators like classes, then I can see the argument for it but still don't think it would be appropriate. For example: my-machine: #"DON'T CHANGE THIS!" 192.168.1.17 The problem with this approach is that I believe that people will be surprised to find out that the simple act of adding a comment to the source file changes their data from a simple scalar into a map. This is unlike any other language in existence (that I know of). Most lexers actually skip over comments so that they never even end up in the parse tree. It looks like you might not be allowing this syntax, though, and would rather make the user explicitly turn a scalar with a comment into a map like in Oren's example above. My question is then, why make them use the # key? If it's just adding an extra pair that will get ignored by the application, then why don't we let them use whatever key they wanted to? For example, I'd much rather see this: my-machine: %= address: 192.168.1.17 warning: DON'T CHANGE THIS! several clients access this address directly - talk with the Network Administrator first. Here the first pair is the default (do we still like this?) and the second pair is just an extra pair that would get ignored by the application reading this file because it doesn't know about it and is probably going to use Clark's asScalar() or Oren's v() function anyways so would always get the default value as it were and never even see the warning key. The advantages to this approach are: 1) Users are explicitly adding a key and so can't claim to be surprised when they encounter a map during parsing. 2) The # indicator is free to be used or not used elsewhere. 3) More than one comment can be added to a node. 4) There will never be any question as to whether or not comments are part of the information model and can be ignored since there will no longer be comments (in the traditional sense). 5) Requiring user's to make up an appropriate key name is more verbose but conveys more information to anybody reading the source from then on (like how I renamed # to warning above). This is true even if they use the key "comment"--that's still more clear to me than "#". Can somebody come up with some disadvantages? I can't think of any. Jason. |
From: Clark C . E. <cc...@cl...> - 2001-06-18 14:08:44
|
Jason brings up a good point, is the comment/class/whatever indicator short-hand more trouble than what it is worth? ... On Sun, Jun 17, 2001 at 01:33:41PM -0700, Jason Diamond wrote: | my-machine: % | =: 192.168.1.17 | #: DON'T CHANGE THIS! several clients | access this address directly - talk | with the Network Administrator first. | | I think that this is an excellent example of why substitutability is | important and why our APIs should support it. Colors are very powerful, but I think going in this direction means that the users of our language will have to "buy-in". | However, I think that introducing a comment construct into the | language would be a mistake. Do we really need a special | comment key? I think the value is standardization; if we have a few "common" colors one can make a standard filter (as Oren describes) which strips the common colors. This filter can be built-into the parser as a parameter... | my-machine: #"DON'T CHANGE THIS!" 192.168.1.17 | | The problem with this approach is that I believe that | people will be surprised to find out that the simple | act of adding a comment to the source file changes | their data from a simple scalar into a map. week: ^iso8601 1999W06 week: !org.clarkevans.Week 1999W06 Personally, I don't like comments written using the same-line short hand. However, for the above examples using a !class or ^encoding might be very useful indeed. In this case, the user would have to undersand that the above examples are not scalars... or... perhaps we should drop this "confusing" short hand? | This is unlike any other language in existence (that | I know of). Most lexers actually skip over | comments so that they never even end up in the parse tree. Right, but no other languages that I know of have anything similar to the Color (substitutability) mechanism... | my-machine: %= | address: 192.168.1.17 | warning: DON'T CHANGE THIS! several clients | access this address directly - talk | with the Network Administrator first. | | Here the first pair is the default (do we still like this?) Good question. The problem with the "first pair" is that it only works at parse time. Thus, first pair is an option with the "%=" construct, which requires a specific YamlObject imlementation, where if we use the language's native objects we are stuck with the equal sign... my-machine: % =: 192.168.1.17 #: DON'T CHANGE THIS! Several clients access this address directly -- talk with the Network Admin first. | 1) Users are explicitly adding a key and so can't claim to be | surprised when they encounter a map during parsing. Do we do the same (require specific annotations) for class and possibly encoding? week: % =: 1999W06 !: org.clarkevans.Week Hmm. The above is more clear. Oren? What do you think? Should we eliminate the "short-hand". It may reduce confusion. | 2) The # indicator is free to be used or not used elsewhere. Right... however, having a "standard" for denoting what is a comment (or class respectively) will allow for a common "strip comments/class/encoding/whatever" filter... | 3) More than one comment can be added to a node. Nothing saying people couldn't use "comment" or "JMS-NOTE:" or what ever. It just won't be easily colored by syntax coloring or auto-filtered with a simple "-c" switch, etc. | 4) There will never be any question as to whether or not comments are part | of the information model and can be ignored since there will no longer be | comments (in the traditional sense). Right. | 5) Requiring user's to make up an appropriate key name is more verbose but | conveys more information to anybody reading the source from then on (like | how I renamed # to warning above). This is true even if they use the key | "comment"--that's still more clear to me than "#". Nothing stopping people from doing this! Best, Clark |