From: Hugh Sasse Staff Elec Eng <hgs@...>
Date: 2003-08-23T02:13:59+09:00
Subject: tentative pre-rcr: text balancing in REs

I've been trying to put some notes together about OpenGL in Fox, for
which there is limited documentation.  The way FXRuby is
constructed, using SWIG, naturally means that comments don't make it
from the C++ into Ruby, which is fair enough: language differences
would make this a nonsense anyway.  So to get descriptions of the
functions I have been going through manually extracting the comments
into html.  This was repetitive and boring, so I wanted to automate
it.

The easiest way to automate detecting a function body with a leading
comment, to my mind, was to use lua, for the reasons below.
The meat of the code is
-------8<---------------------
     local file = io.open(arg[i], "r")
     if file then
         contents = file:read("*a")
         pattern = "\n%s-\n// ([^\n]*)\n(%a+%s+[^(\n]+%b())%b{}"
         for com, sig in string.gfind(contents, pattern) do
             print("<dt><span class=\"def\">" .. sig .. "</span></dt>")
             print("<dd>" .. com .. "</dd>")
         end
         io.close(file)
     else
         print(arg[i] .. " does not exist\n")
     end
-------8<---------------------

That was the first version that worked.  (string.gfind works in the
for loop as an iterator, and .. is concatenate for strings. The rest
is probably prettty clear. )
The good bit is the pattern. Lua uses % where we use \ in regexps
for character classes like \s, \d, so this looks for a comment (com)
after a blank line, and thn it looks for the signature of a
function declaration (sig) thusly:
(               # begin capture
%a+             # A bunch of letters (void, long,....)
%s+[^(\n]+      # whitespace followed by anything but '(' and '\n'
%b()            # Balanced brackets and whatever they contain
)               # End capture
%b{}            # Balanced braces and whatever they contain


It is this balanced brackets and braces that made this conceptually
easy in lua.  It didn't really matter how convoluted the function
body was, it would balance and thus be matched.  Well, there could
be case that would break it, but the general nesting would not.

My wish is to have Ruby Regexps support something similar. \b is
already taken (backspace) so instead of "brackets" maybe
"parenthesis", suggesting \p, perhaps?


Having built my castle in the air :-), I now suggest that a small
town grows up around it:

In lua %bxy balances the characters x and y.  If something similar
made it into ruby, could we go further, to have
\p(<h1>)(</h1>)
i.e. pick out balanced strings, or maybe balanced regexps?

Caveats:
I'm not familiar with the internals of ruby's regexps.
This may be unsuitable for ruby because of those internals, and my
generalized extension of this is likely to be hideously expensive to
implement and/or run, leading to match times of hours in nasty cases.

So my question is this: "Is this too foolish to even comtemplate it
as an RCR?"  Lua is a language so committed to small size that it
didn't have a for loop until version 4 (IIRC), so I think this
implies there is merit in this feature.  But I've already been wrong
about adding non-inheritable class variables this week, so I won't
put this into the RCR process without support.

        Thank you,
        Hugh