ERb Request

[matt]

Could someone point me to the ERb Homepage, or whom I need to email to
make a feature request for ERb.

Thanks,

Matt

PS. I'm wanting to request that there be a way to make comments in
large chunks (like /* */ in C or <!-- --> in HTML), but in a way that I
can comment my .rhtml files, without the comments being passed on to the
generated code. This way I can make proper documentation comments in my
code, without having to give away any information to the general public.

 

[Phrogz]

Could someone point me to the ERb Homepage, or whom I need to email to
make a feature request for ERb.

Discuss the feature request on this mailing list. If, after discussion,
you feel it has strong merit, it can be brought up on the ruby-core
mailing list.

PS. I'm wanting to request that there be a way to make comments in
large chunks (like /* */ in C or <!-- --> in HTML), but in a way that I
can comment my .rhtml files, without the comments being passed on to the
generated code. This way I can make proper documentation comments in my
code, without having to give away any information to the general public.

What would you like it to look like? What edge cases can you think of,
and how should they be handled?

 

[matt]

Well what it looks like is a bit of preference, and it should stick with
ERb's '<%' tagging convention, so something like '<%*' and '*%>'

It will absolutely need to have mandatory start and end tags that are
distinguishable from other tags, and be able to ignore all data and
information within these tags, sending nothing to the browser (or other
stream)

As far as boundary cases, I think that the following would need to be
considered to start, but I'm sure there are others:

1. nested block comments should be checked
<%* <%* *%> *%>

2. N start tags and N-1 stop tags
<%* <%* *%>

3. M start tags and M+1 stop tags
<%* *%> *%>

4. Handling of mixed HTML and ERb block comments, both overlapping and
not.
ie.

Erb Comment within HTML Comment
<!-- <%* *%> -->

Overlapping HTML/ERb comment
<!-- <%* --> *%>


I'm sure there are other boundaries to consider, I just can't think of
them off the top of my skull.

My thoughts on a block comment are to allow the developer a bit more
flexibility in documenting the limited amount of coding that belongs in
a Rails View (or any place that a .rhtml file would be used). We all
know what every for loop is doing when we write it, but returning a few
months later can be agonizing without crucial comments/documentation.

Our current solutions are HTML comments, and ERb comments. HTML
comments are passed on to the generated view, so any proprietary
information or inside information that others (hackers, kids,
pranksters, etc) is still displayed, but commented. As well the HTML
style comments don't prevent the ERb parser from parsing the
information, so if you are trying to comment out a section of code that
doesn't seem to be working, the ERb parser still analyzes it, though
doesn't generate the code.

ERb style comments are great for simple text documentation, or single
line code comments, but all too often, I've found myself wanting to
block out large chunks of mixed code (HTML and Ruby) that isn't working,
without losing my working context. My choices are to HTML comment out
the block (to catch all the HTML content) and then to single line
comment out all the embedded Ruby.

By making a block comment for embedded Ruby, there would be a way to
section out large parts of code quickly, easily, and still maintain
continuity of work.

Matt

 

[James Edward Gray II]

PS. I'm wanting to request that there be a way to make comments in
large chunks (like /* */ in C or <!-- --> in HTML), but in a way
that I
can comment my .rhtml files, without the comments being passed on
to the
generated code. This way I can make proper documentation comments
in my
code, without having to give away any information to the general
public.

ERb supports this today:

$ cat erb_comment.txt
This is
<%# This is an ERb comment...
it's clever enough to let it span multiple lines -%>
a test.
$ erb -T - erb_comment.txt
This is
a test.

James Edward Gray II

 

[matt]

Yes, it can span several lines of text,

But is it clever enough to:

<%#
<% for photo in @listing.photos %>
<% and more Ruby processing in an rhtml file %>
%>


The request is primarily for 2 things within an rhtml file (possibly
other applications):

1) block comments of ERb code
2) non-processing / non-display of these block comments


Matt

 

[James Edward Gray II]

Yes, it can span several lines of text,

But is it clever enough to:

<%#
<% for photo in @listing.photos %>
<% and more Ruby processing in an rhtml file %>
%>

No. ERb doesn't support nested tags.

The request is primarily for 2 things within an rhtml file (possibly
other applications):

1) block comments of ERb code
2) non-processing / non-display of these block comments

I like the idea. As a workaround, use your editor's ability to find
and replace in a selection, swapping <% for <%#.

James Edward Gray II

 

[Phrogz]

Well what it looks like is a bit of preference, and it should stick with
ERb's '<%' tagging convention, so something like '<%*' and '*%>'

It will absolutely need to have mandatory start and end tags that are
distinguishable from other tags, and be able to ignore all data and
information within these tags, sending nothing to the browser (or other
stream)

Here's a simple patch that does this:

[sliver:/usr/local/lib/ruby/1.8] gkistner$ diff -u erb.rb
erb_with_block_comment.rb
--- erb.rb 2006-12-31 10:53:06.000000000 -0700
+++ erb_with_block_comment.rb 2006-12-31 10:54:01.000000000 -0700
@@ -688,7 +688,7 @@
@safe_level = safe_level
compiler = ERB::Compiler.new(trim_mode)
set_eoutvar(compiler, eoutvar)
- @src = compiler.compile(str)
+ @src = compiler.compile(str.gsub(/<%\*.+?\*%>/m,''))
@filename = nil
end

Probably this would be better implemented as part of the scanner for
ERB, but this could be a base test for desired functionality around
edge cases.

1. nested block comments should be checked
<%* <%* *%> *%>

What do you mean by 'checked'? Allowing nesting, or throw an error?
The simple hack I provided above fails on nested comments.

Is this really important? As far as I know, C++, JavaScript and Ruby
all disallow the nesting of their block comment style. Lua allowed it
in 5.0, but as of 5.1 it requires that the author use unique block
comment delimiters for each nested level.

It's certainly doable...but is the performance cost worth it?

2. N start tags and N-1 stop tags
<%* <%* *%>

I would say that, like other languages, this case should be treated
fine. (You're asking ERB to ignore all things that look like ERB
commands inside the block comment; shouldn't that include ignoring
something that looks like a block comment start?

The hack I have above treats this as a single block comment.

3. M start tags and M+1 stop tags
<%* *%> *%>

The hack I have above treats this case as degenerate, leaving a lone
*%> in the source and causing ERB to barf. This seems consistent with
how many other languages handle block comments.

Erb Comment within HTML Comment
<!-- <%* *%> -->

This should emit an HTML comment with no content, correct?

Overlapping HTML/ERb comment
<!-- <%* --> *%>

This should emit broken HTML (an unpaired comment start), since ERB has
no knowledge of SGML/HTML/XML.

By making a block comment for embedded Ruby, there would be a way to
section out large parts of code quickly, easily, and still maintain
continuity of work.

I'm a fan of this idea, just want to make it solid and make an attempt
at a good implementation before asking for a patch on ruby-core.

 

[matt]

Inline comments below.

Well what it looks like is a bit of preference, and it should stick with
ERb's '<%' tagging convention, so something like '<%*' and '*%>'

It will absolutely need to have mandatory start and end tags that are
distinguishable from other tags, and be able to ignore all data and
information within these tags, sending nothing to the browser (or other
stream)

Here's a simple patch that does this:

[sliver:/usr/local/lib/ruby/1.8] gkistner$ diff -u erb.rb
erb_with_block_comment.rb
--- erb.rb 2006-12-31 10:53:06.000000000 -0700
+++ erb_with_block_comment.rb 2006-12-31 10:54:01.000000000 -0700
@@ -688,7 +688,7 @@
@safe_level = safe_level
compiler = ERB::Compiler.new(trim_mode)
set_eoutvar(compiler, eoutvar)
- @src = compiler.compile(str)
+ @src = compiler.compile(str.gsub(/<%\*.+?\*%>/m,''))
@filename = nil
end

Probably this would be better implemented as part of the scanner for
ERB, but this could be a base test for desired functionality around
edge cases.

I agree, the scanner is where it should be implemented in the end, but
this is a good start.

What do you mean by 'checked'? Allowing nesting, or throw an error?
The simple hack I provided above fails on nested comments.

Checked in the sense of finding the occurrence, throw an error if found.

Is this really important? As far as I know, C++, JavaScript and Ruby
all disallow the nesting of their block comment style. Lua allowed it
in 5.0, but as of 5.1 it requires that the author use unique block
comment delimiters for each nested level.

It's certainly doable...but is the performance cost worth it?


I would say that, like other languages, this case should be treated
fine. (You're asking ERB to ignore all things that look like ERB
commands inside the block comment; shouldn't that include ignoring
something that looks like a block comment start?

I was thinking this would be an error.

What if:
<%* Comment 1 Other Stuff Not Commented <%* Comment 2 *%>

Was supposed to be:
<%* Comment 1 *%> Other Stuff Not Commented <%* Comment 2 *%>

It could certainly be treated as a single block, with a warning in the
logs that the condition was caught and treated as a single block. Or
this could be an environment option that is set on how the author wants
it treated. I personally like things to error out, but I know others
don't.

The hack I have above treats this as a single block comment.


The hack I have above treats this case as degenerate, leaving a lone
*%> in the source and causing ERB to barf. This seems consistent with
how many other languages handle block comments.

Yeah, similar to #2 above

What if:
<%* Comment 1 *%> Other Fine Code Comment 2 *%>


Was supposed to be:
<%* Comment 1 *%> Other Fine Code <%* Comment 2 *%>

This case I think doesn't have a choice but to throw an unrecoverable
error, but should be able to return the last comment tag line number and
position for quick reference.

This should emit an HTML comment with no content, correct?

<!-- HTML Comment 1 <%* ERB Comment *%> HTML Comment 2 -->

Should not process the ERB Comment and the generated HTML would be

This should emit broken HTML (an unpaired comment start), since ERB has
no knowledge of SGML/HTML/XML.

Yeah, since the <%* tags won't process, it will find the first HTML tag
and no matching end.

I'm a fan of this idea, just want to make it solid and make an attempt
at a good implementation before asking for a patch on ruby-core.

Great, I know nothing of the Ruby core, so I'll be of little help there
(for now), but I will always do my part to suggest improvements and
upgrades with as much help and detail as I can provide.



Matt

 

[Aníbal]

I like it, I usually find myself cutting the code instead of commenting
it because of what you are pointing.