s-exp/inline comment syntax

[iacore]

Scheme has #;(...) that allows a block of code to be commented easily.

Please share your idea about how such syntax would be in Janet.

(comment ...) is not the same, since it returns nil.

[primo-ppcg]

Something like this would have worked until recently:

(defmacro ignore [& body]
  ~;[])

(pp (ignore
      this is just a comment.)
    :ok)

:ok

However, this will throw an error as a top level expression:

(ignore
  this is just a comment.)

compile error: splice can only be used in function parameters and data constructors, it has no effect here

[iacore]

So the proposal is to allow top-level splice? Or empty macro as a special case.

I think we do need reader syntax for this case.

[primo-ppcg]

The error produced by an improper usage of a splice is meant to prevent accidental propagation of a splice form. I think it would be preferable to have an empty macro expand to nothing, rather than nil, although this won't be done.

[bakpakin]

The reason this doesn't generally work is that your comment would only work in certain places. For example:

(def (ignore a b c) x 10)

would never have worked. BTW, the posted example does actually work in the latest janet. It is the equivalent of (pp ;[] :ok) which is well formed.

[pepe]

Just my two cents, but for this purpose, I use good old #. I understand that it is not the same as having a particular form, but I use this technique sparingly and mostly lean on git.

[iacore]

# in Janet is line comment
this discussion is about s-exp/inline comment

[pepe]

Yep, as I wrote, I understand that it is not the same, just that I am using it for this purpose.

[pepe]

Anyway, I see little value in this whole discussion.

[sogaiu]

I am not opposed to the idea of block comments that don't evaluate to nil, but I'm not enthusiastic about new syntax.

I can imagine using such a feature and can relate, but so far have survived without it.

I don't know what costs might be involved in carrying out something like this though -- both within Janet itself but also to adapting existing tooling.

AFAIU neither Clojure nor Emacs Lisp have something like this [2] and Scheme does [1], so some Lisp-using folks seem to get by with less. It might be that spelling out (in some detail) the kinds of situations where this idea would be useful could be helpful in getting support.

I think sometimes you don't know what you're missing until you see good uses for it, though of course not always (^^;

Regarding new syntax, this issue contains a fairly recent discussion. It might be helpful background in understanding various folks' views.

Update: added footnote [2] after reducing own confusion.

---

[1] No clue about Common Lisp.

[2] Actually, Clojure has #_ which AFAICT is just like SRFI-62's #; (note that neither require delimiters afterwards).

[pepe]

Not sure what rant you are referring to.

I used the wrong word, I guess. I meant this answer: I would make comment a special form that evaluates to nothing and call it a day.

My apologies rainy day by the sea 😅

[iacore]

I tried it, and made (comment) a special form. It's not quite working for top-level code.

It functions like a comment at top-level, but evaluates to @[] (visible in REPL).

I'm sure that can be fixed.

[CosmicToast]

My apologies rainy day by the sea 😅

Yeah, that's not really a rant. A rant refers to a tirade, a lengthy, wild, passionate speech, which can often be boisterous, nonsensical, and raving.
Indeed, I meant it as a brief comment of little value besides offering one potential solution. :)

[primo-ppcg]

Note that this can't be a special form easily either

It's essentially the same as the macro.

[bakpakin]

The macro/special form does not work and cannot work in a reasonable way. All other special forms and macros would need to understand how to handle comments since they would be retained by the parser. The correct and simple way to do this is to extend the parser. Janet also will not support arbitrary reader macros.

[bakpakin]

Possibly this is a good use (if somewhat underwhelming) of our last free special character in the janet syntax, \.

Something like

(def \(This is just a fancy comment) a 10)

Would discard the comment during reading. Backwards compatible and simple.

[sogaiu]

(Unfortunately, some of these comments that are "deeper" may not be seen by others -- one must notice that there is a link to "click" to see them...not a great characteristic for a system that's supposed to be promoting discussions IMO.)

[sogaiu]

I looked at some of the items that @iacore linked to [1] and came across SRFI 62: S-expression comments. The construct described above -- #_ -- seems pretty similar to it. The SRFI one uses #; instead.

The abstract from the SRFI is:

This SRFI proposes a simple extension to Scheme's lexical syntax that allows individual S-expressions to be made into comments, ignored by the reader. This contrasts with the standard Lisp semicolon comments, which make the reader ignore the remainder of the line, and the slightly less common block comments, as SRFI 30 defines: both of these mechanisms comment out slices of text, not S-expressions.

The rationale is:

Line and block comments are useful for embedding textual commentary in programs, but they are not conducive to commenting out code easily in an absence of extensive editor support for removing selected text that composes S-expressions while retaining them in the text itself, or subsequently removing the comments and re-introducing the S-expressions themselves.

SRFI 62 is a pretty short read (and I've quoted a lot it already) ;)

I'll note that the OP has this text:

it allows a block of code to be commented easily.

So I read that concern as having to do more with commenting out code and not necessarily text.

---

[1] In this comment.

[iacore]

Yes, #; is mainly used to comment out code in scheme. You can use it to write block comment as well.

[sogaiu]

My impression so far is that this kind of construct -- #; (SRFI 62) / #_ (Clojure) -- would be nicer, at least from a user perspective. No detailed thoughts about implementation consequences.

For reference, IIRC (memory a bit fuzzy) supporting #_ in tree-sitter-clojure involved redoing the grammar. So I know one way it can be accomplished -- using that way for tree-sitter-janet-simple will mean breaking changes (which might be worth it).

[sogaiu]

LOL, sorry, I've been misreading. I see that the OP is mentioning SRFI 62 (which I presume was what was there originally).

I think part of my mistake was that I didn't look / read closely enough (definitely my bad - sorry!) and assumed wrongly that the parens and dots implied another construct.

@iacore Please consider editing the OP to use #; only -- so without the parens and dots.

[iacore]

Slightly related: Scheme's myriad reader syntax.

In Scheme, # has special meaning. #.(Pi) is implementation-defined data. #() is vector. #;() is comment. #<p></p> is XML. More here

We don't have such a convention in Janet yet, so it's difficult to add new syntax.

P.S. Common Lisp has #.( )

[sogaiu]

So to clarify, IIUC -- SRFI 62's #; and Clojure's #_:

• "operate on" / "affect" the "next" expression [1] -- not arbitrary text
• neither have parens or other dual-delimiters as part of the construct, though one CAN follow the construct with a paren-delimited expression

This is different from typical multi-line comment constructs (e.g. /* + */ in C-ish languages) that "comment out" text which can include strings that aren't "source", and it's different from (comment ...) (which does have an opening and closing delimiter, sort of -- and the ... can have multiple expressions).

Some examples (#_ is a stand-in, it wouldn't be a good choice [2]):

(+ 1 #_ 2 8)  # just the 2 "disappears"

# parses to
(+ 1 8)

#_ first item goes away

# parses to
item goes away

(+ 1 #_ (all of this stuff disappears but each item between parens is treated as a symbol first))

# parses to
(+ 1)

{:alice "restaurant"
 #_ #_ :bob "bunker"
 :charles "choco-factory"}

# parses to
{:alice "restaurant"
 :charles "choco-factory"}

A demo of primo-ppcg's comment:

A big advantage of syntax like this (aside from not evaluating to nil) is that a multi-line form can be commented out at a single location, rather than having to add a matching parenthesis at the end.

(defn my-fn
  [x]
  (print "hi")
  {:fox [:f (* x 2)]
   :elephant [:e math/pi]}
  #_{:ant [:a x]
     :bee [:b 2]}) # note: we don't have to figure out which closing delimiters here with #_.
                   #       using (comment ...) need to carefully place the closing paren
                   #       because of the presence of ] and }
# parses to
(defn my-fn
  [x]
  (print "hi")
  {:fox [:f (* x 2)]
   :elephant [:e math/pi]})

(I'm writing this here because stuff can become obscure and hidden in GH discussions (at lower levels) and I was confused about what was being proposed in the OP (perhaps it was just me (^^; ).)

---

[1] Note that "stacking" can happen.

For example, for:

(+ 1 #_ #_ 2 3 6)

the inner #_ applies to 2 and the outer #_ applies to 3.

(+ 1 #_ #_ 2 3 6)
     |  |  | |
     |  ---- |
     |       |
     ---------

The net result is:

(+ 1 6)

[2] (Note: this footnote was added hours after the initial series of edits -- sorry, primo-ppcg (^^; )

As implied by others ("underwhelming"), I think using \ alone (single character) just for this feature is not worth it.

If \ is to be involved, I think it would be better to use a mutli-byte sequence (similar to what primo-ppcg suggested in concept) where \ is the first character. (I think this arrangement would be backward compatible whereas it's unclear to me whether choosing some other leading character would be.)

Using \ + single character seems similar in flavor to what iacore mentioned here about the use of # in Scheme (e.g. #() is vector, #; discards, etc.). This would potentially allow other sequences beginning with \ in the future.

[primo-ppcg]

I also spent some time thinking about this after the discussion and independently concluded that \# would likely be the best choice. The idea that I had was that \ would start a different type of reader macro ("extended reader macro" or similar) that could allow any token to follow.

While this would utilize the last unassigned character, it would offer some flexibility, as the number of reader macros possible would be essentially limitless.

[sogaiu]

The idea that I had was that \ would start a different type of reader macro ("extended reader macro" or similar) that could allow any token to follow.

It sounds conceptually similar to what iacore mentioned here, and I went for something like that in the attempt.

Does that seem close to what you had in mind?

---

Before using Janet, I was of the opinion that I'd likely want to always (if possible) have some way to keep extending a programming language if necessary. A supporting thought here is something like "who knows what need or idea might arise at some point?".

I'm not so sure I buy this line of thinking any more -- at least I'm not sure it doesn't make sense to start over at some point from time-to-time. It seems likely to me that potentially infinite extensibility may lead to needless complexity and awkward constructs. I think those kinds of things tend to make languages harder to learn, reason about, and maintain, and that's a pretty undesirable thing as far as I'm concerned.

[pepe]

I'm not so sure I buy this line of thinking any more -- at least I'm not sure it doesn't make sense to start over at some point from time-to-time. It seems likely to me that potentially infinite extensibility may lead to needless complexity and awkward constructs. I think those kinds of things tend to make languages harder to learn, reason about, and maintain, and that's a pretty undesirable thing as far as I'm concerned.

I feel the same more and more. 🙏

[primo-ppcg]

Does that seem close to what you had in mind?

Almost exactly that.

It seems likely to me that potentially infinite extensibility may lead to needless complexity and awkward constructs.

Not needing to have the language reference open constantly is the mark of good design. This is more true of Janet than most languages I've used.

Essentially limitless, yes, but how many more reader macros could there really be anyway? Perhaps two or three? My point was that by using \ in this way, the door hasn't been closed forever. You could still add a \& or \@ or whatever else might make sense in the future.

[sogaiu]

My point was that by using \ in this way, the door hasn't been closed forever. You could still add a & or @ or whatever else might make sense in the future.

Sure - as I understand it, that's what at least 3 of us (you, iacore, and yours truly) seem to be concluding / saying in this discussion and I tried to reflect that "open-endedness" in the little coding experiment.

Essentially limitless, yes, but how many more reader macros could there really be anyway? Perhaps two or three?

You may be right. In some sense, I think zero would be the nicest, but perhaps if some compelling thing comes along I might change my mind :)

For the record, I looked a bit into this for Scheme and Clojure...

In Scheme's case it seems there were a bit more than two or three proposed. iacore posted a link earlier that points at page that lists more than 10. It's possible that none of those things actually made it into any of the RnRS standards -- but some folks were interested enough to write stuff up. So with enough of the right people I guess there is sufficient imagination?

I'm not intimately familiar with the history of how things got added to Clojure, but at least currently, one can see what gets "dispatched" via # here.

I think some time after 1.0-ish, at least 4 things got added:

• #^ - for metadata (this was actually a change in the "official" notation IIUC)
• ## - for symbolic values
• #? - for reader conditionals
• #: - for namespaced maps

That's 4 things that are handled by the dispatch reader macro-ish construct, but those were not the only additions to the language. I think tagged literals also got added after 1.0. These are just the things that I happen to be familiar with though. Quite possibly I missed some other things.

I think for both Scheme and Clojure there is kind of an expectation of extensibility.