zsh-workers
 help / color / mirror / Atom feed
* Block comments ala Ray
@ 2021-02-10  6:05 Bart Schaefer
  2021-02-10  6:16 ` Roman Perepelitsa
                   ` (3 more replies)
  0 siblings, 4 replies; 39+ messages in thread
From: Bart Schaefer @ 2021-02-10  6:05 UTC (permalink / raw)
  To: Zsh hackers list

I've been noodling around with Ray Andrew's oft-repeated suggestion of
some kind of block comment syntax.  After considerable prodding of
gettok() in lex.c, I came up with something that works like this:

A line beginning with !# introduces a block comment.  This
(deliberately) means that NO_BANG_HIST must be in effect, so without
some hoop-jumping this only affects scripts.
I chose this because it seems unlikely to me that anyone would write in a script

!# this is just a silly way to mean false

The comment ends after a line containing #! anywhere in the line.  So
a full block could be:

!# This begins a block comment.
This is merely rambling.
This #! is the last line of the block

Stylistically, of course, I'd recommend putting the #! either at the
beginning or the end of that third line, but tokenizing worked best
just consuming everything up through the newline once #! was
recognized.  I experimented with allowing the block comment to start
or end in the middle of lines, but it was just too weird to be able to
do

print this !# part is a comment
but this part #! is not a comment

(which would print "this is not a comment"), and a solo "!" out of
command position may not be as rare as one at the start of a line.

I tried some other character combinations ... for example I can't find
any circumstance in which it is not a syntax error to write <# so if
it's appealing to match that with #> for symmetry, it's a small edit.
But I wasn't happy that those appear to be redirections.

Having told you all that ... there's one glitch with my
implementation.  To detect whether !# is at the beginning of a line,
in gettok() I test the "isnewlin" boolean.  This works everywhere
(that I've found) except when on the first character of a new script
file.  That means you can't begin a script with a block comment ...
which perhaps is a good thing, since typo-ing "!#/bin/sh" may not be
all that uncommon, and having the entire script turn into a comment
would be a bit startling.  However, I would like to know what (if
anything) can be tested to identify the first character of a new
script?  I've tried combinations of of
  isnewlin  -- this is initialized to false
  isfirstch  -- this is true after any separator
  isfirstln  -- true throughout any single-line command
What else could be examined?

Any other thoughts about this?  Too horrible to consider?  It needs
turning off in emulation modes and I haven't gotten to that yet.


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-10  6:05 Block comments ala Ray Bart Schaefer
@ 2021-02-10  6:16 ` Roman Perepelitsa
  2021-02-12  6:17   ` Bart Schaefer
  2021-02-12 20:48 ` Bart Schaefer
                   ` (2 subsequent siblings)
  3 siblings, 1 reply; 39+ messages in thread
From: Roman Perepelitsa @ 2021-02-10  6:16 UTC (permalink / raw)
  To: Bart Schaefer; +Cc: Zsh hackers list

On Wed, Feb 10, 2021 at 7:05 AM Bart Schaefer <schaefer@brasslantern.com> wrote:
>
> The comment ends after a line containing #! anywhere in the line.  So
> a full block could be:
>
> !# This begins a block comment.
> This is merely rambling.
> This #! is the last line of the block

This can be very surprising because it's not how block comments work
in other popular languages. It also disallows inline comments --
something I personally use in other languages.

    foo(/* bar_count */ 42);

I would go even further and say that the value provided by block
comments resides almost exclusively in enabling inline comments. If a
comment consists of several full lines, very little is gained (if
anything at all) by using block comments.

Roman.


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-10  6:16 ` Roman Perepelitsa
@ 2021-02-12  6:17   ` Bart Schaefer
  2021-02-12  6:26     ` Bart Schaefer
                       ` (2 more replies)
  0 siblings, 3 replies; 39+ messages in thread
From: Bart Schaefer @ 2021-02-12  6:17 UTC (permalink / raw)
  To: Zsh hackers list

On Tue, Feb 9, 2021 at 10:16 PM Roman Perepelitsa
<roman.perepelitsa@gmail.com> wrote:
>
> On Wed, Feb 10, 2021 at 7:05 AM Bart Schaefer <schaefer@brasslantern.com> wrote:
> >
> > !# This begins a block comment.
> > This is merely rambling.
> > This #! is the last line of the block
>
> This can be very surprising because it's not how block comments work
> in other popular languages.

I don't find that very compelling, because in shell the alternative is
to prefix every line with "#", which is exactly what Ray wants to
avoid.

It might be possible to force it to look

!#
like this
#!

(that is, require newlines both before and after the delimiters), if
that seems more friendly, but then the question is what

!#
this
#! means

(did the block end, and if it did not then ...)?

> It also disallows inline comments --
> something I personally use in other languages.

Do you have inline comments in the shell now?  Do you only care about
inline comments that don't contain newlines?  As I mentioned, I
experimented with

print this <# is an inline #> comment

because "<#" in any existing script would be a syntax error; but as
soon as you allow newlines within the comment it becomes a verbose
form of backslash-newline continuation, which felt wrong.

Do you disagree with me about how strangely this --

print this <# part is a comment
(lah-di-dah for perhaps hundreds of lines)
but this part #> is the rest of the command

-- implicitly behaves if the embedded newlines can be inlined?

> I would go even further and say that the value provided by block
> comments resides almost exclusively in enabling inline comments.

I think Ray at least disagrees with you, since he's willing to abuse
here-documents for the purpose, which also can't be inlined.

Do you not use block comments to delimit expository paragraphs?


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-12  6:17   ` Bart Schaefer
@ 2021-02-12  6:26     ` Bart Schaefer
  2021-02-12  6:41     ` Roman Perepelitsa
  2021-02-12 15:24     ` Matthew Martin
  2 siblings, 0 replies; 39+ messages in thread
From: Bart Schaefer @ 2021-02-12  6:26 UTC (permalink / raw)
  To: Zsh hackers list

On Thu, Feb 11, 2021 at 10:17 PM Bart Schaefer
<schaefer@brasslantern.com> wrote:
>
> print this <# part is a comment
> (lah-di-dah for perhaps hundreds of lines)
> but this part #> is the rest of the command

Of course one can already do

print this ${:+ stuff is discarded
(as long as there are no unbalanced
quotes or curly braces)
and then this} is the rest of the command

So perhaps it's not worth worrying that there's another way to do that.


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-12  6:17   ` Bart Schaefer
  2021-02-12  6:26     ` Bart Schaefer
@ 2021-02-12  6:41     ` Roman Perepelitsa
  2021-02-12  7:40       ` Stephane Chazelas
                         ` (2 more replies)
  2021-02-12 15:24     ` Matthew Martin
  2 siblings, 3 replies; 39+ messages in thread
From: Roman Perepelitsa @ 2021-02-12  6:41 UTC (permalink / raw)
  To: Bart Schaefer; +Cc: Zsh hackers list

On Fri, Feb 12, 2021 at 7:17 AM Bart Schaefer <schaefer@brasslantern.com> wrote:
>
> On Tue, Feb 9, 2021 at 10:16 PM Roman Perepelitsa
> <roman.perepelitsa@gmail.com> wrote:
> >
> > On Wed, Feb 10, 2021 at 7:05 AM Bart Schaefer <schaefer@brasslantern.com> wrote:
> > >
> > > !# This begins a block comment.
> > > This is merely rambling.
> > > This #! is the last line of the block
> >
> > This can be very surprising because it's not how block comments work
> > in other popular languages.
>
> I don't find that very compelling, because in shell the alternative is
> to prefix every line with "#", which is exactly what Ray wants to
> avoid.

I understand that Ray wants this but I don't know why.

What are the benefits of this:

  !#
  Lorem ipsum
  dolor sit amet
  #!

over this:

  # Lorem ipsum
  # dolor sit amet

?

Do these benefits justify adding new syntax that's unique to zsh?

> Do you have inline comments in the shell now?

No. I use zsh as my main shell and it doesn't support inline comments.

>  Do you only care about
> inline comments that don't contain newlines?

Yes.

I should say that I don't care that much about inline comments. My
point is that I would only ever use block comments as inline comments
with no embedded newlines.

> Do you disagree with me about how strangely this --
>
> print this <# part is a comment
> (lah-di-dah for perhaps hundreds of lines)
> but this part #> is the rest of the command
>
> -- implicitly behaves if the embedded newlines can be inlined?

If this were valid syntax, I would expect it to work like in C. In
other words, I would expect there to be two commands:

  print this
  is the rest of the command

> I think Ray at least disagrees with you, since he's willing to abuse
> here-documents for the purpose, which also can't be inlined.

Ray does many things that I wouldn't recommend ;-)

> Do you not use block comments to delimit expository paragraphs?

No. I mostly write C++ and I use single-line comments for everything
except inline comments (those that don't span until the end of the
line). This is standard practice at Google. I believe this is common
in many other languages that have C-like comments (Java, C#, etc.).
Whenever I worked on a code base that used block comments, they
usually looked like this:

  /*
   * Lorem ipsum
   * dolor sit amet
   */

And almost never like this:

  /*
  Lorem ipsum
  dolor sit amet
  */

So block comments in my experience are most often used as if they were
single-line comments.

Roman.


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-12  6:41     ` Roman Perepelitsa
@ 2021-02-12  7:40       ` Stephane Chazelas
  2021-02-12  7:46         ` Roman Perepelitsa
  2021-02-12 15:30         ` Bart Schaefer
  2021-02-13  4:33       ` Bart Schaefer
  2021-02-15  0:42       ` Greg Klanderman
  2 siblings, 2 replies; 39+ messages in thread
From: Stephane Chazelas @ 2021-02-12  7:40 UTC (permalink / raw)
  To: Roman Perepelitsa; +Cc: Bart Schaefer, Zsh hackers list

2021-02-12 07:41:50 +0100, Roman Perepelitsa:
[...]
> And almost never like this:
> 
>   /*
>   Lorem ipsum
>   dolor sit amet
>   */
> 
> So block comments in my experience are most often used as if they were
> single-line comments.
[...]

Block comments are useful to comment out sections of code, as in

#if I_STILL_NEEDED_THIS

some
now dead
code

#endif /* I_STILL_NEEDED_THIS */

There's a POSIX sh equivalent for that though:

:||:<<'# some comment'

some
now dead
code

# some comment

(with the added benefit that you can just comment the :||: line
if you find that you want that code after all.

-- 
Stephane


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-12  7:40       ` Stephane Chazelas
@ 2021-02-12  7:46         ` Roman Perepelitsa
  2021-02-12 15:30         ` Bart Schaefer
  1 sibling, 0 replies; 39+ messages in thread
From: Roman Perepelitsa @ 2021-02-12  7:46 UTC (permalink / raw)
  To: Roman Perepelitsa, Bart Schaefer, Zsh hackers list

On Fri, Feb 12, 2021 at 8:40 AM Stephane Chazelas <stephane@chazelas.org> wrote:
>
> 2021-02-12 07:41:50 +0100, Roman Perepelitsa:
> [...]
> > And almost never like this:
> >
> >   /*
> >   Lorem ipsum
> >   dolor sit amet
> >   */
> >
> > So block comments in my experience are most often used as if they were
> > single-line comments.
> [...]
>
> Block comments are useful to comment out sections of code

Indeed. Some projects ban block comments from committed code
specifically to allow one to easily disable a block of code during
development. In C we can employ the preprocessor for this purpose
(which allows for arbitrary nesting) but not all languages are so
lucky.

Roman.


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-12  6:17   ` Bart Schaefer
  2021-02-12  6:26     ` Bart Schaefer
  2021-02-12  6:41     ` Roman Perepelitsa
@ 2021-02-12 15:24     ` Matthew Martin
  2021-02-12 16:18       ` Bart Schaefer
  2 siblings, 1 reply; 39+ messages in thread
From: Matthew Martin @ 2021-02-12 15:24 UTC (permalink / raw)
  To: zsh-workers

On Thu, Feb 11, 2021 at 10:17:10PM -0800, Bart Schaefer wrote:
> Do you have inline comments in the shell now?

echo foo `# a comment` bar

Might even be POSIX though I'm not a language lawyer.


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-12  7:40       ` Stephane Chazelas
  2021-02-12  7:46         ` Roman Perepelitsa
@ 2021-02-12 15:30         ` Bart Schaefer
  2021-02-12 15:45           ` Stephane Chazelas
  1 sibling, 1 reply; 39+ messages in thread
From: Bart Schaefer @ 2021-02-12 15:30 UTC (permalink / raw)
  To: Zsh hackers list

On Thu, Feb 11, 2021 at 11:40 PM Stephane Chazelas
<stephane@chazelas.org> wrote:
>
> :||:<<'# some comment'

That's exactly what the zsh-users discussion has been telling Ray he
should not do, because at some point it's not going to work the way he
expects.


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-12 15:30         ` Bart Schaefer
@ 2021-02-12 15:45           ` Stephane Chazelas
  2021-02-12 16:55             ` Bart Schaefer
  0 siblings, 1 reply; 39+ messages in thread
From: Stephane Chazelas @ 2021-02-12 15:45 UTC (permalink / raw)
  To: Bart Schaefer; +Cc: Zsh hackers list

2021-02-12 07:30:23 -0800, Bart Schaefer:
> On Thu, Feb 11, 2021 at 11:40 PM Stephane Chazelas
> <stephane@chazelas.org> wrote:
> >
> > :||:<<'# some comment'
> 
> That's exactly what the zsh-users discussion has been telling Ray he
> should not do, because at some point it's not going to work the way he
> expects.
[...]

How so?

That construct is pretty idiomatic.

Note:
- the :|| to prevent the temp file containing the here-doc from
  even being created and
- the *quoted* delimiter (here "# some comment") to prevent
  expansions being performed inside the here-doc

That can even be aliased:

alias START_COMMENT=':||:<<"END_COMMENT"'

How would it be different from your !# .. #! ?

-- 
Stephane


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-12 15:24     ` Matthew Martin
@ 2021-02-12 16:18       ` Bart Schaefer
  2021-02-15 21:30         ` Daniel Shahaf
  0 siblings, 1 reply; 39+ messages in thread
From: Bart Schaefer @ 2021-02-12 16:18 UTC (permalink / raw)
  To: zsh-workers

On Fri, Feb 12, 2021 at 7:24 AM Matthew Martin <phy1729@gmail.com> wrote:
>
> echo foo `# a comment` bar

Forking a no-op process just to make it look like a comment isn't my
idea of a comment.


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-12 15:45           ` Stephane Chazelas
@ 2021-02-12 16:55             ` Bart Schaefer
  2021-02-12 18:16               ` Lawrence Velázquez
  2021-02-15 22:28               ` Daniel Shahaf
  0 siblings, 2 replies; 39+ messages in thread
From: Bart Schaefer @ 2021-02-12 16:55 UTC (permalink / raw)
  To: Bart Schaefer, Zsh hackers list

On Fri, Feb 12, 2021 at 7:45 AM Stephane Chazelas <stephane@chazelas.org> wrote:
>
> 2021-02-12 07:30:23 -0800, Bart Schaefer:
> > On Thu, Feb 11, 2021 at 11:40 PM Stephane Chazelas
> > <stephane@chazelas.org> wrote:
> > >
> > > :||:<<'# some comment'
> >
> > That's exactly what the zsh-users discussion has been telling Ray he
> > should not do, because at some point it's not going to work the way he
> > expects.
> [...]
>
> How so?

What was said on zsh-users (not by me):

"Here-documents are not comments, despite your best efforts to abuse
them for that role."

"The construct you use has side-effects you've overlooked, which mean
your fashion of comments will backfire in a way that you don't see yet."

(Paraphrased) There are places where you might want comments but that
command syntax is not allowed, for example in the midst of "for ...
do".

> How would it be different from your !# .. #! ?

For one thing, the content of a here-document is "compiled" into the
wordcode of the script or function, even if the command referencing
that here-document is never going to execute.   True comments are
discarded during lexing.


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-12 16:55             ` Bart Schaefer
@ 2021-02-12 18:16               ` Lawrence Velázquez
  2021-02-12 21:02                 ` Stephane Chazelas
  2021-02-15 22:28               ` Daniel Shahaf
  1 sibling, 1 reply; 39+ messages in thread
From: Lawrence Velázquez @ 2021-02-12 18:16 UTC (permalink / raw)
  To: Bart Schaefer, Stephane Chazelas; +Cc: zsh-workers

> On Feb 12, 2021, at 11:55 AM, Bart Schaefer <schaefer@brasslantern.com> wrote:
> 
> On Fri, Feb 12, 2021 at 7:45 AM Stephane Chazelas <stephane@chazelas.org> wrote:
>> 
>> 2021-02-12 07:30:23 -0800, Bart Schaefer:
>>> On Thu, Feb 11, 2021 at 11:40 PM Stephane Chazelas
>>> <stephane@chazelas.org> wrote:
>>>> 
>>>> :||:<<'# some comment'
>>> 
>>> That's exactly what the zsh-users discussion has been telling Ray he
>>> should not do, because at some point it's not going to work the way he
>>> expects.
>> [...]
>> 
>> How so?
> 
> What was said on zsh-users (not by me):
> 
> "Here-documents are not comments, despite your best efforts to abuse
> them for that role."

This was me, addressing someone with shaky shell fundamentals who
was aliasing the here-document idiom and expecting it to behave
identically to real comments (discarded during lexing, no further
impact on the script).

Naturally, the remark is rather less applicable to someone who
remains aware of the nature and limitations of the idiom.

vq

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-10  6:05 Block comments ala Ray Bart Schaefer
  2021-02-10  6:16 ` Roman Perepelitsa
@ 2021-02-12 20:48 ` Bart Schaefer
  2021-02-13  8:35 ` Stephane Chazelas
  2021-02-16 15:30 ` Juergen Christoffel
  3 siblings, 0 replies; 39+ messages in thread
From: Bart Schaefer @ 2021-02-12 20:48 UTC (permalink / raw)
  To: Zsh hackers list

On Tue, Feb 9, 2021 at 10:05 PM Bart Schaefer <schaefer@brasslantern.com> wrote:
>
> I would like to know what (if
> anything) can be tested to identify the first character of a new
> script?  I've tried combinations of of
>   isnewlin  -- this is initialized to false
>   isfirstch  -- this is true after any separator
>   isfirstln  -- true throughout any single-line command
> What else could be examined?

Nobody knows this?


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-12 18:16               ` Lawrence Velázquez
@ 2021-02-12 21:02                 ` Stephane Chazelas
  2021-02-12 21:12                   ` Stephane Chazelas
  0 siblings, 1 reply; 39+ messages in thread
From: Stephane Chazelas @ 2021-02-12 21:02 UTC (permalink / raw)
  To: Lawrence Velázquez; +Cc: Bart Schaefer, zsh-workers

2021-02-12 13:16:28 -0500, Lawrence Velázquez:
[...]
> This was me, addressing someone with shaky shell fundamentals who
> was aliasing the here-document idiom and expecting it to behave
> identically to real comments (discarded during lexing, no further
> impact on the script).
[...]

Thanks all for the clarifications.

About "discarding during lexing", I did find these btw:

$ ksh93 -c $'f() {\n# whatever\necho  x\n}; typeset -f f'
f() {
# whatever
echo  x
}

It appears as if they're not discarded(though it looks like it's
rather that ksh stores the raw text content (probably only for
the "typeset -f" output) in addition to "compiling"/"wordcoding"
or however you want to call it (which probably still discards
comments)).

But see also (as that construct was mentioned in that thread):

$ zsh -c 'f() { echo `echo x # comment`; }; typeset -f f; f'
f () {
        echo `echo x # comment`
}
x
$ mksh -c 'f() { echo `echo x # comment`; }; typeset -f f; f'
f() {
        \echo $(echo x # comment)
}
x
$ bash -c 'f() { echo `echo x # comment`; }; typeset -f f; f'
f ()
{
    echo `echo x # comment`
}
x

as the parsing of the inside of `...` is deferred in all shells
except ash-based ones; see $shell -c ':||echo `for`'. A bit like
in eval 'echo x # comment'.

It's also deferred with the $(...) form in bash (but bash only
AFAICT):

$ bash -c $'f() { echo $(echo x # comment\n); }; typeset -f f'
f ()
{
    echo $(echo x # comment
)
}

That newline is necessary in all shells though there, and that
makes the replacing of `...` with $(...) in the typeset -f
output by mksh above incorrect:

~$ mksh -c 'f() { echo `echo x # comment`; }; typeset -f f' | mksh
mksh: <stdin>[3]: syntax error: unexpected '}'

-- 
Stephane


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-12 21:02                 ` Stephane Chazelas
@ 2021-02-12 21:12                   ` Stephane Chazelas
  2021-02-12 21:29                     ` Bart Schaefer
  0 siblings, 1 reply; 39+ messages in thread
From: Stephane Chazelas @ 2021-02-12 21:12 UTC (permalink / raw)
  To: Lawrence Velázquez, Bart Schaefer, zsh-workers

2021-02-12 21:02:36 +0000, Stephane Chazelas:
[...]
> as the parsing of the inside of `...` is deferred in all shells
> except ash-based ones; see $shell -c ':||echo `for`'. A bit like
> in eval 'echo x # comment'.
> 
> It's also deferred with the $(...) form in bash (but bash only
> AFAICT):
> 
> $ bash -c $'f() { echo $(echo x # comment\n); }; typeset -f f'
> f ()
> {
>     echo $(echo x # comment
> )
> }
[...]

Hmmm, actually in zsh, there is parsing going on there:

$ zsh -c 'f() { echo $(for); }; typeset -f f'
zsh: parse error near `)'
zsh:1: parse error near `$(for); }; typeset -...'

But still, the comments appear not to be discarded at that point:

$ zsh -c $'f() { echo $(echo x # comment\n); }; typeset -f f; f'
f () {
        echo $(echo x # comment
)
}
x

-- 
Stephane


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-12 21:12                   ` Stephane Chazelas
@ 2021-02-12 21:29                     ` Bart Schaefer
  2021-02-13  7:37                       ` Stephane Chazelas
  0 siblings, 1 reply; 39+ messages in thread
From: Bart Schaefer @ 2021-02-12 21:29 UTC (permalink / raw)
  To: Lawrence Velázquez, Bart Schaefer, zsh-workers

On Fri, Feb 12, 2021 at 1:12 PM Stephane Chazelas <stephane@chazelas.org> wrote:
>
> But still, the comments appear not to be discarded at that point:
>
> $ zsh -c $'f() { echo $(echo x # comment\n); }; typeset -f f; f'
> f () {
>         echo $(echo x # comment
> )
> }
> x

The literal text of what's contained in $(...) is retained, but not
comments in the function body itself.

% Src/zsh -f <<<$'f() { # this is a comment\necho $(echo x #
comment\n); }; typeset -f f; f'
f () {
    echo $(echo x # comment
)
}
x


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-12  6:41     ` Roman Perepelitsa
  2021-02-12  7:40       ` Stephane Chazelas
@ 2021-02-13  4:33       ` Bart Schaefer
  2021-02-15  0:42       ` Greg Klanderman
  2 siblings, 0 replies; 39+ messages in thread
From: Bart Schaefer @ 2021-02-13  4:33 UTC (permalink / raw)
  To: Roman Perepelitsa; +Cc: Zsh hackers list

On Thu, Feb 11, 2021 at 10:42 PM Roman Perepelitsa
<roman.perepelitsa@gmail.com> wrote:
>
> Do these benefits justify adding new syntax that's unique to zsh?

It's not as though zsh doesn't have lots of other unique syntax.

> On Fri, Feb 12, 2021 at 7:17 AM Bart Schaefer <schaefer@brasslantern.com> wrote:
> >
> > Do you disagree with me about how strangely this --
> >
> > print this <# part is a comment
> > (lah-di-dah for perhaps hundreds of lines)
> > but this part #> is the rest of the command
> >
> > -- implicitly behaves if the embedded newlines can be inlined?
>
> If this were valid syntax, I would expect it to work like in C. In
> other words, I would expect there to be two commands:
>
>   print this
>   is the rest of the command

It turns out not to be very difficult to make !# ... #! (or <# ... #>)
work that way, but ... that's not really how it works in C.  You
wouldn't expect

int /* watch me explain
why this next variable
is not a float */ thing;

to behave like "int; thing;".  My original point is that the shell
doesn't have the syntactic clues to tell you that "print this" (in the
example) is not already a complete command, the way you can tell in C
by the missing semicolon that something must eventually be coming
after "int".


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-12 21:29                     ` Bart Schaefer
@ 2021-02-13  7:37                       ` Stephane Chazelas
  0 siblings, 0 replies; 39+ messages in thread
From: Stephane Chazelas @ 2021-02-13  7:37 UTC (permalink / raw)
  To: Bart Schaefer; +Cc: Lawrence Velázquez, zsh-workers

2021-02-12 13:29:48 -0800, Bart Schaefer:
> On Fri, Feb 12, 2021 at 1:12 PM Stephane Chazelas <stephane@chazelas.org> wrote:
> >
> > But still, the comments appear not to be discarded at that point:
> >
> > $ zsh -c $'f() { echo $(echo x # comment\n); }; typeset -f f; f'
> > f () {
> >         echo $(echo x # comment
> > )
> > }
> > x
> 
> The literal text of what's contained in $(...) is retained
[...]

You're right. It looks like the contents is parsed (I suppose to
be able to handle the case x in x)... and the like inside), but
the result of that parsing seems to be discarded, and it seems
the contents of that $(...) is parsed again each time the
function is invoked.

ksh93 does appear to do the same. bash as well, but it's unclear
to me what kind of parsing it does in the first round.

See for instance:

$ bash -xc 'echo $(foo case a in a); esac)'
++ foo case a in a
bash: foo: command not found
+ echo '; esac)'
; esac)

-- 
Stephane


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-10  6:05 Block comments ala Ray Bart Schaefer
  2021-02-10  6:16 ` Roman Perepelitsa
  2021-02-12 20:48 ` Bart Schaefer
@ 2021-02-13  8:35 ` Stephane Chazelas
  2021-02-13  8:53   ` Stephane Chazelas
                     ` (2 more replies)
  2021-02-16 15:30 ` Juergen Christoffel
  3 siblings, 3 replies; 39+ messages in thread
From: Stephane Chazelas @ 2021-02-13  8:35 UTC (permalink / raw)
  To: Bart Schaefer; +Cc: Zsh hackers list

2021-02-09 22:05:13 -0800, Bart Schaefer:
[...]
> !# This begins a block comment.
> This is merely rambling.
> This #! is the last line of the block
[...]

I can't say I like it much either.

- those !#, #! look too much like a shebang. Also consider
  scripts that do:

  cat > script <<EOF
  #! /bin/sh -
  ...
  EOF

  making it difficult to comment out those codes

- !# is already histsubst syntax.

- It's also the !# extendedglob

- It's also (POSIXly) invoking the !# command.

- syntax is a bit obscure and uncommon. Would we allow blanks
  before the !# for indentation purposes. Would those !# be
  recognised if the previous line ends in a \ or inside
  heredocs? Does it have to be delimited with whitespace? Can we
  use !########### .. ##############!? That ! is easy to miss.
  Would we allow escaping the closing #!? How?

- assuming we allow nesting (which would be useful to comment
  out sections of code that contain block comments), it will be
  harder to follow than with C's #if...#endif or
  :||:<<'EOC'...EOC

Other possible avenues:

- <<# .. #>> allows inline comments, but looks more like a
  redirection operator than a comment.
- alternatively: <<#EOC .. EOC (or <<#{...} <<#[...] and the
  usual pairs) to make nesting easier.
- The =word .. =cut of perl: conflicts with zsh's =cmd operator,
  not nestable put would allow pod inline documentation.

To me, there are more useful features that could be added to zsh
before that one. In that vein, I'm thinking of quotes like
python's '''...''' or perl's q(...)/qq(...) or ruby's %q{...}
operator for things like

ssh host %{
  blah | sed 's/\./.../'
}

Or ksh's <#((...)), <#.. <>;  redirection operators.

-- 
Stephane


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-13  8:35 ` Stephane Chazelas
@ 2021-02-13  8:53   ` Stephane Chazelas
  2021-02-14 20:50     ` Bart Schaefer
  2021-02-14 20:15   ` Bart Schaefer
  2021-02-14 20:58   ` Bart Schaefer
  2 siblings, 1 reply; 39+ messages in thread
From: Stephane Chazelas @ 2021-02-13  8:53 UTC (permalink / raw)
  To: Bart Schaefer, Zsh hackers list

2021-02-13 08:35:21 +0000, Stephane Chazelas:
[...]
> Other possible avenues:
> 
> - <<# .. #>> allows inline comments, but looks more like a
>   redirection operator than a comment.
> - alternatively: <<#EOC .. EOC (or <<#{...} <<#[...] and the
>   usual pairs) to make nesting easier.

That one could allow to improve the 

for a (pod head{1..4} over item back begin end for encoding)
  aliases[=$a]=":||:<<'=cut' #"

We can already use ATM to add pod doc to zsh scripts to:

for a (pod head{1..4} over item back begin end for encoding)
  aliases[=$a]='<<#=cut'

(with the caveat that your pod documentation must not embed a
=cut anywhere, if we allow the delimiter to be anywhere).


> - The =word .. =cut of perl: conflicts with zsh's =cmd operator,
>   not nestable put would allow pod inline documentation.
[...]


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-13  8:35 ` Stephane Chazelas
  2021-02-13  8:53   ` Stephane Chazelas
@ 2021-02-14 20:15   ` Bart Schaefer
  2021-02-15  0:36     ` Vincent Lefevre
  2021-02-15 17:43     ` Stephane Chazelas
  2021-02-14 20:58   ` Bart Schaefer
  2 siblings, 2 replies; 39+ messages in thread
From: Bart Schaefer @ 2021-02-14 20:15 UTC (permalink / raw)
  To: Bart Schaefer, Zsh hackers list

On Sat, Feb 13, 2021 at 12:35 AM Stephane Chazelas
<stephane@chazelas.org> wrote:
>
> 2021-02-09 22:05:13 -0800, Bart Schaefer:
> [...]
> > !# This begins a block comment.
> > This is merely rambling.
> > This #! is the last line of the block
> [...]
>
> - those !#, #! look too much like a shebang.

Which actually doesn't matter, because #! isn't special anywhere but
the first line.

> - !# is already histsubst syntax.

Also doesn't matter, this was intended only to operate where history
is disabled anyway.

> - It's also the !# extendedglob

You mean "zero or more occurrences of '!' "?  This is another reason I
was only allowing "!#" at the start of a line.  Under what
circumstances would you begin a new line with that glob?

> - It's also (POSIXly) invoking the !# command.

Yes, I mentioned that.  It seems pretty damn unlikely to use that, as
it has no effect other than to set $? to 1.

> Also consider
>   scripts that do:
>
>   cat > script <<EOF
>   #! /bin/sh -
>   ...
>   EOF
>
>   making it difficult to comment out those codes

That one has some relevance, and argues for requiring #! to be
followed immediately by a newline, if not also preceded by one.

> - syntax is a bit obscure and uncommon.

Intentionally so, yes.  It has to be something that would essentially
never appear in an existing script.

>   Would we allow blanks
>   before the !# for indentation purposes.

No.

>   Would those !# be
>   recognised if the previous line ends in a \ or inside
>   heredocs?

No, because it's handled by the lexer.  It's not recognized anywhere
any other comment isn't.

>   Does it have to be delimited with whitespace? Can we
>   use !########### .. ##############!? That ! is easy to miss.

Those are among the reasons I didn't think forming "inline comments"
was a good idea.

>   Would we allow escaping the closing #!? How?

No, because you can't escape anything inside a comment.

> - assuming we allow nesting (which would be useful to comment
>   out sections of code that contain block comments),

I hadn't considered nesting.  You can't nest C /* ... */ comments, and
this was not intended to work any differently.

> - <<# .. #>> allows inline comments, but looks more like a
>   redirection operator than a comment.

That's why I rejected <# ... #>.

> To me, there are more useful features that could be added to zsh
> before that one.

This is like saying we should solve problems on earth before we spend
money on space exploration.  It's a false dichotomy.

> Or ksh's <#((...)), <#.. <>;  redirection operators.

The possibility of wanting to add those would also argue against using
"<#" or "<<#" as a comment introducer.


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-13  8:53   ` Stephane Chazelas
@ 2021-02-14 20:50     ` Bart Schaefer
  0 siblings, 0 replies; 39+ messages in thread
From: Bart Schaefer @ 2021-02-14 20:50 UTC (permalink / raw)
  To: Zsh hackers list

On Sat, Feb 13, 2021 at 12:53 AM Stephane Chazelas
<stephane@chazelas.org> wrote:
>
> 2021-02-13 08:35:21 +0000, Stephane Chazelas:
> [...]
> > - alternatively: <<#EOC .. EOC (or <<#{...} <<#[...] and the
> >   usual pairs) to make nesting easier.
>
> That one could allow [...]
>
> for a (pod head{1..4} over item back begin end for encoding)
>   aliases[=$a]='<<#=cut'

It's a lot more difficult to do the lexical analysis if the comment
introducer is more than 2 characters long, because if it turns out NOT
to be a comment you have to be able to "unget" what has been read and
re-lex it.  It's not impossible, but it's ugly; compare all the
messiness trying to determine whether $(( is introducing a math
expression vs. a command substitution starting with a subshell.

My intent is to introduce something similar to /* ... */, not an #if
... #endif equivalent.  For the latter (or poddish) we really would
have to introduce new here-document syntax, and just discard the
document instead of wordcoding it.


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-13  8:35 ` Stephane Chazelas
  2021-02-13  8:53   ` Stephane Chazelas
  2021-02-14 20:15   ` Bart Schaefer
@ 2021-02-14 20:58   ` Bart Schaefer
  2 siblings, 0 replies; 39+ messages in thread
From: Bart Schaefer @ 2021-02-14 20:58 UTC (permalink / raw)
  To: Zsh hackers list

On Sat, Feb 13, 2021 at 12:35 AM Stephane Chazelas
<stephane@chazelas.org> wrote:
>
> I can't say I like it much either.

By the way, I'm not in any way committed to "!#".  It was the only
thing I could come up with that seemed to satisfy other requirements,
so I'm providing my reasoning.  If there's another suggestion that is
as easily lexed, it should definitely be considered.

Or we can just scrap the whole idea, it was essentially just a proof of concept.


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-14 20:15   ` Bart Schaefer
@ 2021-02-15  0:36     ` Vincent Lefevre
  2021-02-15  1:07       ` Bart Schaefer
  2021-02-15 17:43     ` Stephane Chazelas
  1 sibling, 1 reply; 39+ messages in thread
From: Vincent Lefevre @ 2021-02-15  0:36 UTC (permalink / raw)
  To: zsh-workers

On 2021-02-14 12:15:31 -0800, Bart Schaefer wrote:
> On Sat, Feb 13, 2021 at 12:35 AM Stephane Chazelas
> <stephane@chazelas.org> wrote:
> > Also consider
> >   scripts that do:
> >
> >   cat > script <<EOF
> >   #! /bin/sh -
> >   ...
> >   EOF
> >
> >   making it difficult to comment out those codes
> 
> That one has some relevance, and argues for requiring #! to be
> followed immediately by a newline, if not also preceded by one.

This could be very confusing and error prone.

How about the "'' " prefix (two single quotes followed by a space)
to start and end a block comment?

I doubt that a command starting with these characters is something
useful. What follows could then be decided to allow nesting of block
comments.

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-12  6:41     ` Roman Perepelitsa
  2021-02-12  7:40       ` Stephane Chazelas
  2021-02-13  4:33       ` Bart Schaefer
@ 2021-02-15  0:42       ` Greg Klanderman
  2 siblings, 0 replies; 39+ messages in thread
From: Greg Klanderman @ 2021-02-15  0:42 UTC (permalink / raw)
  To: zsh-workers

>>>>> On February 12, 2021 Roman Perepelitsa <roman.perepelitsa@gmail.com> wrote:

> On Fri, Feb 12, 2021 at 7:17 AM Bart Schaefer <schaefer@brasslantern.com> wrote:
>> 
>> > On Wed, Feb 10, 2021 at 7:05 AM Bart Schaefer <schaefer@brasslantern.com> wrote:
>> > >
>> > > !# This begins a block comment.
>> > > This is merely rambling.
>> > > This #! is the last line of the block

Those look almost like backwards inline Lisp comments..

> line). This is standard practice at Google. I believe this is common

Do you work at Google?  I see a Constantine, but not Roman..
but maybe that is you?

cheers,
Greg


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-15  0:36     ` Vincent Lefevre
@ 2021-02-15  1:07       ` Bart Schaefer
  2021-02-15  1:38         ` Vincent Lefevre
  0 siblings, 1 reply; 39+ messages in thread
From: Bart Schaefer @ 2021-02-15  1:07 UTC (permalink / raw)
  To: zsh-workers

On Sun, Feb 14, 2021 at 4:36 PM Vincent Lefevre <vincent@vinc17.net> wrote:
>
> How about the "'' " prefix (two single quotes followed by a space)

Not very visually distinctive, especially for two single quotes then
space then newline.

Also as I mentioned, it's significantly more work if the introducer is
more than two characters, because of the need to back up and re-lex if
it turns out not to be a comment.  It's easy to peek one character
ahead of "!" and unget the peek if it isn't "#".  To use more than two
characters means turning the whole thing into a real lexical token
rather than just something thrown away during lexing (as happens with
comments at present).

Hm, what about paren then ampersand?  Doesn't conflict with ksh
pattern-list syntax, is currently a syntax error, etc.  The problem
being that the reverse (ampersand paren) could appear in valid code,
so the end marker would have to be asymmetric to remove that
objection.


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-15  1:07       ` Bart Schaefer
@ 2021-02-15  1:38         ` Vincent Lefevre
  0 siblings, 0 replies; 39+ messages in thread
From: Vincent Lefevre @ 2021-02-15  1:38 UTC (permalink / raw)
  To: zsh-workers

On 2021-02-14 17:07:23 -0800, Bart Schaefer wrote:
> On Sun, Feb 14, 2021 at 4:36 PM Vincent Lefevre <vincent@vinc17.net> wrote:
> >
> > How about the "'' " prefix (two single quotes followed by a space)
> 
> Not very visually distinctive, especially for two single quotes then
> space then newline.

Note that this is only a prefix. You can decide what you want to
write after it.

> Also as I mentioned, it's significantly more work if the introducer is
> more than two characters, because of the need to back up and re-lex if
> it turns out not to be a comment.

Can't this be shared with the usual parsing and decide after reading
the first word? Here, this would normally correspond to an "empty"
command.

> It's easy to peek one character ahead of "!" and unget the peek if
> it isn't "#". To use more than two characters means turning the
> whole thing into a real lexical token rather than just something
> thrown away during lexing (as happens with comments at present).

But here, the 3rd character is just a word delimiter, so that I would
think that this is simpler.

> Hm, what about paren then ampersand?  Doesn't conflict with ksh
> pattern-list syntax, is currently a syntax error, etc.  The problem
> being that the reverse (ampersand paren) could appear in valid code,
> so the end marker would have to be asymmetric to remove that
> objection.

Could you give an example of valid code with "&)" at the beginning
of a line?

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-14 20:15   ` Bart Schaefer
  2021-02-15  0:36     ` Vincent Lefevre
@ 2021-02-15 17:43     ` Stephane Chazelas
  2021-02-15 22:06       ` Daniel Shahaf
  1 sibling, 1 reply; 39+ messages in thread
From: Stephane Chazelas @ 2021-02-15 17:43 UTC (permalink / raw)
  To: Bart Schaefer; +Cc: Zsh hackers list

2021-02-14 12:15:31 -0800, Bart Schaefer:
[...]
> > - those !#, #! look too much like a shebang.
> 
> Which actually doesn't matter, because #! isn't special anywhere but
> the first line.
> 
> > - !# is already histsubst syntax.
> 
> Also doesn't matter, this was intended only to operate where history
> is disabled anyway.
> 
> > - It's also the !# extendedglob
> 
> You mean "zero or more occurrences of '!' "?  This is another reason I
> was only allowing "!#" at the start of a line.  Under what
> circumstances would you begin a new line with that glob?
> 
> > - It's also (POSIXly) invoking the !# command.
> 
> Yes, I mentioned that.  It seems pretty damn unlikely to use that, as
> it has no effect other than to set $? to 1.

Those were more objections on style ground than to say it was
an incompatible change.

I can imagine someone seeing:

!#
some
code
#! end

And thinking "is that remnants of mistyped shebang?", "why 0 or
more !s?", "what's that history expansion doing in there...?".

[...]
> > - syntax is a bit obscure and uncommon.
> 
> Intentionally so, yes.  It has to be something that would essentially
> never appear in an existing script.

I rather meant "something that one would not readily associate
to a block comment", though I'll admit that none of the
alternatives I suggested are any better.

[...]
> >   Does it have to be delimited with whitespace? Can we
> >   use !########### .. ##############!? That ! is easy to miss.
> 
> Those are among the reasons I didn't think forming "inline comments"
> was a good idea.
[...]
> > - assuming we allow nesting (which would be useful to comment
> >   out sections of code that contain block comments),
> 
> I hadn't considered nesting.  You can't nest C /* ... */ comments, and
> this was not intended to work any differently.

But the only use I can imagine for those !#...#! block comments
are to comment out code. That's why you use #if 0 in C for that
(so you can comment out code that contains comments).

I wouldn't use those for commenting (for inline documentation),
just like in C, we use

/*
 * multiline
 * comment
 */

For long comments as comments formatted as:

/*

  multiline
  comment

*/

make the code less legible as it's less clear what is code and
what is comment.

I could use a C-like comment that allows me to do things like:

rsync -v --inplace \
  --stats -xazAX --delete \
  --numeric-ids !# don't want the dependency on NSS #! \
  --hardlinks

Though at the moment, we can already do:

rsync_options=( -v --inplace
  --stats -xazAX --delete
  --numeric-ids # don't want the dependency on NSS
  --hardlinks
)
rsync $rsync_options

[...]
> > Or ksh's <#((...)), <#.. <>;  redirection operators.
> 
> The possibility of wanting to add those would also argue against using
> "<#" or "<<#" as a comment introducer.

Yes, that's why I didn't suggest <#.

And also why I brought up those ksh93 operators, to suggests
there are more lexer changes that we may want to add to zsh in
the future.

Here, if it was my call, I would just not bother with a new
block-comment operator, at least not until one gave a good
reason why they would be useful and better than what we already
have.

-- 
Stephane


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-12 16:18       ` Bart Schaefer
@ 2021-02-15 21:30         ` Daniel Shahaf
  2021-02-15 22:35           ` Bart Schaefer
  0 siblings, 1 reply; 39+ messages in thread
From: Daniel Shahaf @ 2021-02-15 21:30 UTC (permalink / raw)
  To: zsh-workers

Bart Schaefer wrote on Fri, Feb 12, 2021 at 08:18:07 -0800:
> On Fri, Feb 12, 2021 at 7:24 AM Matthew Martin <phy1729@gmail.com> wrote:
> >
> > echo foo `# a comment` bar
> 
> Forking a no-op process just to make it look like a comment isn't my
> idea of a comment.

Could we optimize away the fork, like «$(<foo)»?  That would enable Stephane's
rsync example from workers/48056.


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-15 17:43     ` Stephane Chazelas
@ 2021-02-15 22:06       ` Daniel Shahaf
  2021-02-15 22:39         ` Bart Schaefer
  0 siblings, 1 reply; 39+ messages in thread
From: Daniel Shahaf @ 2021-02-15 22:06 UTC (permalink / raw)
  To: Zsh hackers list

Stephane Chazelas wrote on Mon, Feb 15, 2021 at 17:43:56 +0000:
> Here, if it was my call, I would just not bother with a new
> block-comment operator, at least not until one gave a good
> reason why they would be useful and better than what we already
> have.

+1

The only reason/justification/use-case given so far was that Ray doesn't want
to prefix each line with "#".  That use-case may have been addressed by the
fact that Ray's $EDITOR turned out to have a "Comment/Uncomment multiple lines"
feature after all (users/26376).


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-12 16:55             ` Bart Schaefer
  2021-02-12 18:16               ` Lawrence Velázquez
@ 2021-02-15 22:28               ` Daniel Shahaf
  1 sibling, 0 replies; 39+ messages in thread
From: Daniel Shahaf @ 2021-02-15 22:28 UTC (permalink / raw)
  To: Zsh hackers list

Bart Schaefer wrote on Fri, Feb 12, 2021 at 08:55:04 -0800:
> On Fri, Feb 12, 2021 at 7:45 AM Stephane Chazelas <stephane@chazelas.org> wrote:
> >
> > 2021-02-12 07:30:23 -0800, Bart Schaefer:
> > > On Thu, Feb 11, 2021 at 11:40 PM Stephane Chazelas
> > > <stephane@chazelas.org> wrote:
> > > >
> > > > :||:<<'# some comment'
> > >
> > > That's exactly what the zsh-users discussion has been telling Ray he
> > > should not do, because at some point it's not going to work the way he
> > > expects.
> > [...]
> >
> > How so?
> 
> What was said on zsh-users (not by me):
> 
> "Here-documents are not comments, despite your best efforts to abuse
> them for that role."
> 
> "The construct you use has side-effects you've overlooked, which mean
> your fashion of comments will backfire in a way that you don't see yet."

For context, that's me from users/26342.  The original paragraph also spells
out that the "side-effects" in question are that lastval will be reset.

> (Paraphrased) There are places where you might want comments but that
> command syntax is not allowed, for example in the midst of "for ...
> do".
> 
> > How would it be different from your !# .. #! ?
> 
> For one thing, the content of a here-document is "compiled" into the
> wordcode of the script or function, even if the command referencing
> that here-document is never going to execute.   True comments are
> discarded during lexing.
> 


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-15 21:30         ` Daniel Shahaf
@ 2021-02-15 22:35           ` Bart Schaefer
  0 siblings, 0 replies; 39+ messages in thread
From: Bart Schaefer @ 2021-02-15 22:35 UTC (permalink / raw)
  To: Daniel Shahaf; +Cc: zsh-workers

On Mon, Feb 15, 2021 at 1:30 PM Daniel Shahaf <d.s@daniel.shahaf.name> wrote:
>
> > On Fri, Feb 12, 2021 at 7:24 AM Matthew Martin <phy1729@gmail.com> wrote:
> > >
> > > echo foo `# a comment` bar
>
> Could we optimize away the fork, like «$(<foo)»?

Not easily.  The contents of $(...) and `...` are given a rudimentary
parse, but are preserved verbatim, so my reading is that shell has
already forked before it "knows" that the entire substitution is a
comment.  "$(<" can be treated specially because the tokens are
recognized.


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-15 22:06       ` Daniel Shahaf
@ 2021-02-15 22:39         ` Bart Schaefer
  0 siblings, 0 replies; 39+ messages in thread
From: Bart Schaefer @ 2021-02-15 22:39 UTC (permalink / raw)
  To: Daniel Shahaf; +Cc: Zsh hackers list

On Mon, Feb 15, 2021 at 2:07 PM Daniel Shahaf <d.s@daniel.shahaf.name> wrote:
>
> Stephane Chazelas wrote on Mon, Feb 15, 2021 at 17:43:56 +0000:
> > Here, if it was my call, I would just not bother with a new
> > block-comment operator
>
> +1

That's fine.  This started as an investigation into how difficult it
would be to modify the lexer, so having found a case where it was not
difficult, I presented it.

Which I also did in order to provide context for my question about
detecting the first character of an entire script, for which I still
don't have an answer.


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-10  6:05 Block comments ala Ray Bart Schaefer
                   ` (2 preceding siblings ...)
  2021-02-13  8:35 ` Stephane Chazelas
@ 2021-02-16 15:30 ` Juergen Christoffel
  2021-02-16 17:21   ` Vincent Lefevre
  2021-02-16 18:21   ` pod documentation in zsh scripts (Was: Block comments ala Ray) Stephane Chazelas
  3 siblings, 2 replies; 39+ messages in thread
From: Juergen Christoffel @ 2021-02-16 15:30 UTC (permalink / raw)
  To: Bart Schaefer; +Cc: Zsh hackers list

On Tue, Feb 09, 2021 at 10:05:13PM -0800, Bart Schaefer wrote:
>
>Any other thoughts about this?  Too horrible to consider?  It needs
>turning off in emulation modes and I haven't gotten to that yet.

While I love to use zsh for various scripts, I switch to e.g. perl for more
complicated / larger scripts (because doing everything in a shell looks
like using the mythical hammer which regards everything as a nail ;-)

That said, wouldn't it be possible to augment the comment parsing to use
something like perl's "plain old documentation" (pod) meachnism, e.g.

#=pod
This is a block comment
and $foo would not have a special meaning inside it
really
#=cut

This "#=" would allow to introduce more control statements inside the block
comment later on, just like perl's pod, which uses it's own little markup
language inside those blocks to mark up text

Cheers, JC

P.S. Even the use of the here document for block comments look less
horrible to me, because it's easily recognized when looking at a script.

-- 
  It is easier to port a shell than a shell script.
	-- Larry Wall


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-16 15:30 ` Juergen Christoffel
@ 2021-02-16 17:21   ` Vincent Lefevre
  2021-02-16 18:29     ` Bart Schaefer
  2021-02-16 21:35     ` Juergen Christoffel
  2021-02-16 18:21   ` pod documentation in zsh scripts (Was: Block comments ala Ray) Stephane Chazelas
  1 sibling, 2 replies; 39+ messages in thread
From: Vincent Lefevre @ 2021-02-16 17:21 UTC (permalink / raw)
  To: Juergen Christoffel; +Cc: Bart Schaefer, Zsh hackers list

On 2021-02-16 16:30:49 +0100, Juergen Christoffel wrote:
> That said, wouldn't it be possible to augment the comment parsing to use
> something like perl's "plain old documentation" (pod) meachnism, e.g.
> 
> #=pod
> This is a block comment
> and $foo would not have a special meaning inside it
> really
> #=cut

This could break existing scripts... unless a specific switch is added
(but more generally, you could imagine a feature that would optionally
preprocess the script before it is parsed by zsh).

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)


^ permalink raw reply	[flat|nested] 39+ messages in thread

* pod documentation in zsh scripts (Was: Block comments ala Ray)
  2021-02-16 15:30 ` Juergen Christoffel
  2021-02-16 17:21   ` Vincent Lefevre
@ 2021-02-16 18:21   ` Stephane Chazelas
  1 sibling, 0 replies; 39+ messages in thread
From: Stephane Chazelas @ 2021-02-16 18:21 UTC (permalink / raw)
  To: Juergen Christoffel; +Cc: Bart Schaefer, Zsh hackers list

2021-02-16 16:30:49 +0100, Juergen Christoffel:
[...]
> That said, wouldn't it be possible to augment the comment parsing to use
> something like perl's "plain old documentation" (pod) meachnism, e.g.
[...]
> P.S. Even the use of the here document for block comments look less
> horrible to me, because it's easily recognized when looking at a script.
[...]

As discussed earlier in this thread, here docs can already be
(ab)used to add pod documentation to zsh scripts. An example one
could look like:

#! /bin/zsh -

for a (pod head{1..4} over item back begin end for encoding)
  aliases[=$a]=":||:<<'=cut' #"

=encoding utf8

=head1 NAME

mytool - blah

=head1 SYNOPSIS

B<mytool> [B<-f>] [B<-h>] [B<-o> I<flag>]...

=head1 DESCRIPTION

B<mytool> does cool stuff

=head1 OPTIONS

=over
=cut

flag=false
opt=()
while getopts hfo: o; do
  case $o in
    (f) flag=true

=item B<-f>

turns a flag on
=cut

  ;;(o) opt+=("$OPTARG")

=item B<-o> I<opt>

to pass some optional value
=cut

  ;;(h) LESS=${LESS}RFX exec perldoc -oterm $0:P

=item B<-h>

show this manual.

=back
=cut

  ;;(*) exit 1
  esac
done

=head1 AUTHOR

Stéphane
=cut


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-16 17:21   ` Vincent Lefevre
@ 2021-02-16 18:29     ` Bart Schaefer
  2021-02-16 21:35     ` Juergen Christoffel
  1 sibling, 0 replies; 39+ messages in thread
From: Bart Schaefer @ 2021-02-16 18:29 UTC (permalink / raw)
  To: Zsh hackers list; +Cc: Juergen Christoffel

On Tue, Feb 16, 2021 at 9:21 AM Vincent Lefevre <vincent@vinc17.net> wrote:
>
> (but more generally, you could imagine a feature that would optionally
> preprocess the script before it is parsed by zsh).

source <(perldoc myscript)

??


^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Block comments ala Ray
  2021-02-16 17:21   ` Vincent Lefevre
  2021-02-16 18:29     ` Bart Schaefer
@ 2021-02-16 21:35     ` Juergen Christoffel
  1 sibling, 0 replies; 39+ messages in thread
From: Juergen Christoffel @ 2021-02-16 21:35 UTC (permalink / raw)
  To: Zsh hackers list

On Tue, Feb 16, 2021 at 06:21:32PM +0100, Vincent Lefevre wrote:
>
>This could break existing scripts... unless a specific switch is added
>(but more generally, you could imagine a feature that would optionally
>preprocess the script before it is parsed by zsh).

Correct, this might need a specific switch. That would suit me fine, e.g.
something (similar to perl, again ;-) like

  require 5.16

or even better

  require zsh 5.3.1

which might later on hopefully lead to some shared solution like

  require bash 4.3.2

and could replace incantations like

  if [[ -z "$ZSH_VERSION" ]]  ; then
      echo $0: need zsh && exit 1
  fi

which I currently use to make sure certain scripts are not executed with
bash. 

	--jc

-- 
  I love deadlines. I love the whooshing sound they make as they fly by.
	-- Douglas Adams


^ permalink raw reply	[flat|nested] 39+ messages in thread

end of thread, other threads:[~2021-02-16 21:35 UTC | newest]

Thread overview: 39+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-02-10  6:05 Block comments ala Ray Bart Schaefer
2021-02-10  6:16 ` Roman Perepelitsa
2021-02-12  6:17   ` Bart Schaefer
2021-02-12  6:26     ` Bart Schaefer
2021-02-12  6:41     ` Roman Perepelitsa
2021-02-12  7:40       ` Stephane Chazelas
2021-02-12  7:46         ` Roman Perepelitsa
2021-02-12 15:30         ` Bart Schaefer
2021-02-12 15:45           ` Stephane Chazelas
2021-02-12 16:55             ` Bart Schaefer
2021-02-12 18:16               ` Lawrence Velázquez
2021-02-12 21:02                 ` Stephane Chazelas
2021-02-12 21:12                   ` Stephane Chazelas
2021-02-12 21:29                     ` Bart Schaefer
2021-02-13  7:37                       ` Stephane Chazelas
2021-02-15 22:28               ` Daniel Shahaf
2021-02-13  4:33       ` Bart Schaefer
2021-02-15  0:42       ` Greg Klanderman
2021-02-12 15:24     ` Matthew Martin
2021-02-12 16:18       ` Bart Schaefer
2021-02-15 21:30         ` Daniel Shahaf
2021-02-15 22:35           ` Bart Schaefer
2021-02-12 20:48 ` Bart Schaefer
2021-02-13  8:35 ` Stephane Chazelas
2021-02-13  8:53   ` Stephane Chazelas
2021-02-14 20:50     ` Bart Schaefer
2021-02-14 20:15   ` Bart Schaefer
2021-02-15  0:36     ` Vincent Lefevre
2021-02-15  1:07       ` Bart Schaefer
2021-02-15  1:38         ` Vincent Lefevre
2021-02-15 17:43     ` Stephane Chazelas
2021-02-15 22:06       ` Daniel Shahaf
2021-02-15 22:39         ` Bart Schaefer
2021-02-14 20:58   ` Bart Schaefer
2021-02-16 15:30 ` Juergen Christoffel
2021-02-16 17:21   ` Vincent Lefevre
2021-02-16 18:29     ` Bart Schaefer
2021-02-16 21:35     ` Juergen Christoffel
2021-02-16 18:21   ` pod documentation in zsh scripts (Was: Block comments ala Ray) Stephane Chazelas

zsh-workers

This inbox may be cloned and mirrored by anyone:

	git clone --mirror http://inbox.vuxu.org/zsh-workers

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V1 zsh-workers zsh-workers/ http://inbox.vuxu.org/zsh-workers \
		zsh-workers@zsh.org
	public-inbox-index zsh-workers

Example config snippet for mirrors.
Newsgroup available over NNTP:
	nntp://inbox.vuxu.org/vuxu.archive.zsh.workers


code repositories for the project(s) associated with this inbox:

	https://git.vuxu.org/mirror/zsh/

AGPL code for this site: git clone https://public-inbox.org/public-inbox.git