Subject: Inline comments?

From: [email-masked] (Sam Robertson)
Date: Thu, 14 Oct 1999 12:19:10 -0700

I'm trying to provide end-user UI and store some necessary 'flags' or
'code' within a line in the sieve code, but in order to make my UI as
flexible as possible I need to have inline comments like the /* */ in
C/C++ in Sieve.  I could easily just use # comments and split a simple
line of code up over multiple lines, but that affects readability which
makes administration difficult without my UI.

Has there been any consideration of adding inline comments, and if not
is there anything that would prevent us from supporting this in Sieve?

Example:  if size :over /* this is an inline comment */ 100K { # this is
a comment
                discard;
             }

Obviously the text within and including the /* */ would be ignored as
white space.  I can live with the text: "body" not allowing comments,
and thus not requiring any kind of special processing beyond
dot-stuffing and EOM.

Any thoughts here?

Sam

---

From: Tony Hansen <[email-masked]>
Date: Thu, 14 Oct 1999 15:59:11 -0400

> and thus not requiring any kind of special processing beyond

Sounds worthy of supporting.

	Tony Hansen
	[email-masked]

---

From: [email-masked] (Sam Robertson)
Date: Tue, 19 Oct 1999 12:23:01 -0700

Anyone else have any thoughts on this?  Is this something we might be
able to add to the next version of the draft?

Sam

---

From: Tim Showalter <[email-masked]>
Date: 20 Oct 1999 19:26:51 -0700

> able to add to the next version of the draft?

I'm sorry I put off responding to this.

I'm not fond of it, but other than feature creep, I have no objection
to it.  I would like to know, though, what you're hiding in comments.
If it's important enough to have in the script, it would seem to be
important enough to represent in the syntax.

Thanks...

Tim

---

From: [email-masked] (Sam Robertson)
Date: Wed, 20 Oct 1999 19:47:11 -0700

Tim,

Thanks for the response.  What I'm trying to do is build a flexible UI
that let's administrators create any 'sieve' script they want while at
the same time being able to present the script to the user in some kind
of real world representation.  The reason for this, is that we don't
think many admins would want users to have the ability to write their
own scripts, but we don't want to restrict administrators to only
providing the scripts we come up with.

So, what I've done is use the comments to hide certain 'key' information
that makes it possible for the parsing engine that presents this
flexible UI to figure out where user selectable fields would go.  I
can't think of another way of offering such a UI without requiring an
admin to write their own code for each of the scripts.  

In a typical example this is what an administrator would create as a
template for the UI:

disclaimer:  This is just an idea that I came up with, and is not
necessarily the easiest or best way to implement it, but this shows what
I think to be a fairly simple way to implement flexible UI.

---- template1.txt ---- 
# $Rule Info: Template="File To Folder" 
if header :is <Q1> <Q2> 
{ 
            fileinto <Q3>; 
} 

#PRE: This rule files messages to a folder 
#PRE: Choose the header field like "Sender" to search on 
#PRE: And specify the value you wish to search for 
#Q1:$header:Header field you wish to search on 
#Q2:$value:Value to search for 
#Q3:$folder: Folder to file to 
#POST: Be sure to adjust the order of this rule 
---- end template1.txt ---- 

The UI javascript or possibly the httpd server's cgi (we are trying to
make this html based) would parse this out and create a page that looks
like:

+---------------------------------------------------------------+ 
| Template: File To Folder             Name: _________________  | 
+---------------------------------------------------------------+ 
|           This rule files messages to a folder                | 
|     Choose the header field like "Sender" to search on        | 
|       And specify the value you wish to search for            | 
|                                                               | 
|   Header field you wish to search on: [o           ]          | 
|   Value to search for: _____________________________          | 
|   Folder to file to: [o              ]                        | 
|                                                               | 
|          Be sure to adjust the order of this rule             | 
+---------------------------------------------------------------+ 

[o             ] are pull down menus with the appropriate items 
________________ is an editable entry box 

>From this, the UI (server or client) creates the finished sieve code:

---- sieveRuleSource value ---- 
#$Rule Info: Order=1 Template="File To Folder" Name="Sam's Spam Rule" 

if header :is /* Q1 */ "Subject" /* /Q1 */ /* Q2 */ "SPAM" /* /Q2 */
{ 
            fileinto /* Q3 */ "spamfolder" /* /Q3 */; 
} 

#PRE: This rule files messages to a folder 
#PRE: Choose the header field like "Sender" to search on 
#PRE: And specify the value you wish to search for 
#Q1:$header:Header field you wish to search on 
#Q2:$value:Value to search for 
#Q3:$folder: Folder to file to 
#POST: Be sure to adjust the order of this rule 
---- sieveRuleSource value ---- 

Now, this code would work if /* */ were ignored by all sieve parsers,
otherwise we would have to translate this code in some kind of
pre-processor for it to be transportable between implementations.

Anyway, you asked for what I'm thinking about, and so you got it.  If
you have some other ideas in mind, I'm very interested in hearing them.

Sam

---

From: Tim Showalter <[email-masked]>
Date: 21 Oct 1999 17:24:08 -0700

> and thus not requiring any kind of special processing beyond

To simplify the lexer's problem a bit, only a # comment is allowed
after "text:".  I really don't want a /**/ comment there, but I'd be
happy to change it to disallow ALL comments.

Here's the change to the nroff source.  Please look at the grammar and 
tell me if I got the bracketed comment production right.

There's nothing Sieve-related going on at the IETF to the best of my
knowledge.  I'll Last Call this real soon now, especially if this is
the only change.

If anyone has any outstanding changes to the vacation spec, I'd like
to know about those as well.

--- sieve.ms.19991021	Thu Oct 21 15:50:54 1999
+++ sieve.ms	Thu Oct 21 17:20:40 1999
@@ -471,10 +471,12 @@
 
 .xx "2.3.     Comments"
 
-Comments begin with a "#" character that is not contained within a string and
-continue until the next CRLF.  Comments are semantically equivalent to
+Two types of comments are offered.  Comments are semantically equivalent to
 whitespace and can be used anyplace that whitespace is (with one exception in
 multi-line strings, as described in the grammar).
+
+Hash comments begin with a "#" character that is not contained within a string
+and continue until the next CRLF.
 .xm
 if size :over 100K { # this is a comment
 .RS
@@ -483,6 +485,18 @@
 }
 .xy
 
+Bracketed comments begin with the token "/*" and end with "*/".
+Bracketed comments may span multiple lines.  Bracketed comments do not
+nest.
+.xm
+if size :over 100K { /* this is a comment
+.RS
+this is still a comment */
+discard /* this is a comment */ ;
+.RE
+}
+.xy
+
 .xx "2.4.     Literal Data"
 
 Literal data means data that is not executed, merely evaluated "as is", to be
@@ -537,8 +551,9 @@
 before each line which begins with a `.'.  When the server interprets the
 script, these extra dots are removed.
 
-Note that a comment or whitespace may occur in between the "text:" and the
-CRLF, but not within the string itself.
+Note that a hashed comment or whitespace may occur in between the "text:" and
+the CRLF, but not within the string itself.  Bracketed comments are not
+allowed here.
 
 .xx "2.4.2.1. String Lists"
 
@@ -1608,11 +1623,22 @@
 described in [ABNF]):
 
 .nf
+bracket-comment = ("/*" *(CHAR-NOT-STAR / ("*" CHAR-NOT-SLASH)) *"*")
+	;; No */ allowed inside a comment.
+	;; (No * is allowed unless it is the last character,
+	;; or unless it is followed by a character that isn't a slash.
+
 CHAR-NOT-DOT = (%x01-2d / %x2f-%xff)
 
 CHAR-NOT-CRLF = (%x01-09 / %x0b-%x0c / %x0e-%xff)
 
-comment = "#" *CHAR-NOT-CRLF CRLF
+CHAR-NOT-SLASH = (%x00-57 / %x58-ff)
+
+CHAR-NOT-STAR = (%x00-51 / %x53-ff)
+
+comment = bracket-comment / hash-comment
+
+hash-comment = ( "#" *CHAR-NOT-CRLF CRLF )
 
 identifier = (ALPHA / "_") *(ALPHA DIGIT "_")
 
@@ -1628,7 +1654,7 @@
 .\" " dirty hack
 	;; note that newlines and other characters are all allowed strings
 
-multi-line = "text:" *(SP / HTAB) (comment / CRLF)
+multi-line = "text:" *(SP / HTAB) (hash-comment / CRLF)
 	*((1*CHAR-NOT-DOT *CHAR CRLF) / ("." 1*CHAR-NOT-DOT *CHAR CRLF) /
 	  (".." *CHAR CRLF) / CRLF)

---

From: Lawrence Greenfield <[email-masked]>
Date: 21 Oct 1999 20:59:18 -0400

[...]

I would greatly prefer that these comments do nest since I think it
makes more sense logically and allows use of such comments to comment
out large sections of code (the only use I would have for these
comments over the "#"-style).

Since I still doubt the utility of these comments (a parsing engine
can just as easily parse the actual Sieve script instead of simply
looking for certain comments) I'm not really attached to having them
nest.

Larry

---

From: Tony Hansen <[email-masked]>
Date: Fri, 22 Oct 1999 12:47:13 -0400

Lawrence Greenfield wrote:
> 
> [...] Bracketed comments do not nest.
> 
> comments over the "#"-style). ...

I could live either way.

	Tony Hansen
	[email-masked]

---

From: Tony Hansen <[email-masked]>
Date: Fri, 22 Oct 1999 12:44:23 -0400

> happy to change it to disallow ALL comments.

I started out to say that /**/ comments should be allowed there, but the
more I thought about it, the more problems I saw. (E.g., what happens if
a /**/ comment wants to span lines after the "text:", how about only
allowing single-line /**/ comments there, ugh, double-ugh, etc. :-) ) At
the same time, I think that allowing one type of comment there but not
the other is a mistake. So I'm agreeing with you that it would be better
to disallow all types of comments after "text:" up to the CRLF.

	Tony Hansen
	[email-masked]

---

From: Lawrence Greenfield <[email-masked]>
Date: 22 Oct 1999 13:06:54 -0400

[...]

The problem with the "text:" construct is that it differentiates one
sort of whitespace (SPC) from another (CRLF).  Since we already do
that, I don't really have a problem with comments there.  Comments
should be equivalent to whitespace.

If I can remove a /* */ and insert a SPC and have a legal program,
then the comment should be legal.

If I can remove a #... and insert a CRLF and have a legal program,
then the comment should be legal.

Larry

Date: 22 Oct 1999 13:06:54 -0400
From: Lawrence Greenfield <[email-masked]>
To: [email-masked]
Subject: Re: Inline comments?
Sender: [email-masked]

[...]

The problem with the "text:" construct is that it differentiates one
sort of whitespace (SPC) from another (CRLF).  Since we already do
that, I don't really have a problem with comments there.  Comments
should be equivalent to whitespace.

If I can remove a /* */ and insert a SPC and have a legal program,
then the comment should be legal.

If I can remove a #... and insert a CRLF and have a legal program,
then the comment should be legal.

Larry

Date: Fri, 22 Oct 1999 12:47:13 -0400
From: Tony Hansen <[email-masked]>
Organization: AT&T Laboratories
To: Lawrence Greenfield <[email-masked]>
CC: [email-masked]
Subject: Re: Inline comments?
Sender: [email-masked]

I could live either way.

	Tony Hansen
	[email-masked]

Date: Fri, 22 Oct 1999 12:44:23 -0400
From: Tony Hansen <[email-masked]>
Organization: AT&T Laboratories
To: [email-masked]
Subject: Re: Inline comments?
Sender: [email-masked]

	Tony Hansen
	[email-masked]

Date: 21 Oct 1999 20:59:18 -0400
From: Lawrence Greenfield <[email-masked]>
To: [email-masked]
Subject: Re: Inline comments?
Sender: [email-masked]

[...]

Larry

To: [email-masked]
Subject: Re: Inline comments?
From: Tim Showalter <[email-masked]>
Date: 21 Oct 1999 17:24:08 -0700
Lines: 102
Sender: [email-masked]

 
 .xx "2.3.     Comments"

 

 
@@ -1608,11 +1623,22 @@
 described in [ABNF]):
 
 .nf

 
 
@@ -1628,7 +1654,7 @@
 .\" " dirty hack

Date: Wed, 20 Oct 1999 19:47:11 -0700
From: [email-masked] (Sam Robertson)
Organization: Netscape Communications, Despair Division
To: Tim Showalter <[email-masked]>
CC: [email-masked]
Subject: Re: Inline comments?
Sender: [email-masked]

Tim,

---- sieveRuleSource value ---- 

Sam

> important enough to represent in the syntax.

To: [email-masked] (Sam Robertson)
Cc: [email-masked]
Subject: Re: Inline comments?
From: Tim Showalter <[email-masked]>
Date: 20 Oct 1999 19:26:51 -0700
Lines: 15
Sender: [email-masked]

Thanks...

Tim

Date: Tue, 19 Oct 1999 12:23:01 -0700
From: [email-masked] (Sam Robertson)
Organization: Netscape Communications, Despair Division
To: [email-masked]
Subject: Re: Inline comments?
Sender: [email-masked]

Sam

> Sounds worthy of supporting.

Date: Thu, 14 Oct 1999 15:59:11 -0400
From: Tony Hansen <[email-masked]>
Organization: AT&T Laboratories
To: Sam Robertson <[email-masked]>
CC: [email-masked]
Subject: Re: Inline comments?
Sender: [email-masked]

	Tony Hansen
	[email-masked]

Date: Thu, 14 Oct 1999 12:19:10 -0700
From: [email-masked] (Sam Robertson)
Organization: Netscape Communications, Despair Division
To: [email-masked]
Subject: Inline comments?
Sender: [email-masked]

Any thoughts here?

Sam