WikiCreole 0.1.0

data/COPYING

@@ -0,0 +1,340 @@
+		    GNU GENERAL PUBLIC LICENSE
+		       Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.
+                       59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+			    Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Library General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+		    GNU GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term "modification".)  Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+  1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+  2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) You must cause the modified files to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    b) You must cause any work that you distribute or publish, that in
+    whole or in part contains or is derived from the Program or any
+    part thereof, to be licensed as a whole at no charge to all third
+    parties under the terms of this License.
+
+    c) If the modified program normally reads commands interactively
+    when run, you must cause it, when started running for such
+    interactive use in the most ordinary way, to print or display an
+    announcement including an appropriate copyright notice and a
+    notice that there is no warranty (or else, saying that you provide
+    a warranty) and that users may redistribute the program under
+    these conditions, and telling the user how to view a copy of this
+    License.  (Exception: if the Program itself is interactive but
+    does not normally print such an announcement, your work based on
+    the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+    a) Accompany it with the complete corresponding machine-readable
+    source code, which must be distributed under the terms of Sections
+    1 and 2 above on a medium customarily used for software interchange; or,
+
+    b) Accompany it with a written offer, valid for at least three
+    years, to give any third party, for a charge no more than your
+    cost of physically performing source distribution, a complete
+    machine-readable copy of the corresponding source code, to be
+    distributed under the terms of Sections 1 and 2 above on a medium
+    customarily used for software interchange; or,
+
+    c) Accompany it with the information you received as to the offer
+    to distribute corresponding source code.  (This alternative is
+    allowed only for noncommercial distribution and only if you
+    received the program in object code or executable form with such
+    an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+  5. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+  6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+  7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+  9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+  10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+			    NO WARRANTY
+
+  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+		     END OF TERMS AND CONDITIONS
+
+	    How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program; if not, write to the Free Software
+    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+    Gnomovision version 69, Copyright (C) year name of author
+    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+  `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+  <signature of Ty Coon>, 1 April 1989
+  Ty Coon, President of Vice
+
+This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Library General
+Public License instead of this License.

data/Changelog

@@ -0,0 +1,2 @@
+2008-12-10 (0.1.0)
+  * Initial Rubyforge Version

data/LICENSE

@@ -0,0 +1,52 @@
+WikiCreole is copyrighted free software by Gordon McCreight
+<gordon@mccreight.com>.  You can redistribute it and/or modify it under either
+the terms of the GPL (see COPYING file), or the conditions below:
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+	  modifications to Usenet or an equivalent medium, or by allowing
+	  the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) rename any non-standard executables so the names do not conflict
+	  with standard executables, which must also be provided.
+
+       d) make other distribution arrangements with the author.
+
+  3. You may distribute the software in object code or executable
+     form, provided that you do at least ONE of the following:
+
+       a) distribute the executables and library files of the software,
+	  together with instructions (in the manual page or equivalent)
+	  on where to get the original distribution.
+
+       b) accompany the distribution with the machine-readable source of
+	  the software.
+
+       c) give non-standard executables non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  4. You may modify and include the part of the software into any other
+     software (possibly commercial).
+
+  5. The scripts and library files supplied as input to or produced as 
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whomever generated them, 
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.

data/README

@@ -0,0 +1,13 @@
+== WikiCreole
+  WikiCreole is a Creole-to-XHTML converter written in pure Ruby.  It supports
+  Creole 1.0 as well as extensions.  Check out the rdoc documentation by issuing
+  the following command:
+    ri WikiCreole
+
+== Synopsis
+  require 'wiki_creole'
+  xhtml = WikiCreole.creole_parse(creole_markup_string)
+
+== Contribute
+  http://github.com/gmccreight/wikicreole/tree/master
+  or send an email to creole.to.gordon@mccreight.com

data/lib/wiki_creole.rb

@@ -0,0 +1,1023 @@
+# WikiCreole implements the Wiki Creole markup language, 
+# version 1.0, as described at http://www.wikicreole.org.  It
+# reads Creole 1.0 markup and returns XHTML.
+#
+# Author::    Gordon McCreight  (mailto:wikicreole.to.gordon@mccreight.com)
+# Copyright:: Copyright (c) 2008 Gordon McCreight
+# License::   Distributes under the same terms as Ruby (see the LICENCE file)
+#
+# == Synopsis
+# Most likely you'll just want to do:
+#  require 'wiki_creole'
+#  xhtml = WikiCreole.creole_parse(wiki_creole_markup)
+# If you want to override the default behaviors, make sure to look at the other
+# public methods.
+#
+# == Official Markup
+#
+#  Here is a summary of the official Creole 1.0 markup 
+#  elements.  See http://www.wikicreole.org for the full
+#  details.
+#
+#  Headings:
+#  = heading 1       ->    <h1>heading 1</h1>
+#  == heading 2      ->    <h2>heading 2</h2>
+#  ...
+#  ====== heading 6  ->    <h6>heading 6</h6>
+#
+#  Various inline markup:
+#  ** bold **        ->    <strong> bold </strong>
+#  // italics //     ->    <em> italics </em>
+#  **// both //**    ->    <strong><em> both </em></strong>
+#  [[ link ]]        ->    <a href="link">link</a>
+#  [[ link | text ]] ->    <a href="link">text</a>
+#  http://cpan.org   ->    <a href="http://cpan.org">http://cpan.org</a>
+#  line \\ break     ->    line <br /> break
+#  {{img.jpg|alt}}   ->    <img src="img.jpg" alt="alt">
+#
+#  Lists:
+#  * unordered list        <ul><li>unordered list</li>
+#  * second item               <li>second item</li>
+#  ## nested ordered  ->       <ol><li>nested ordered</li>
+#  *** uber-nested                 <ul><li>uber-nested</li></ul>
+#  * back to level 1           </ol><li>back to level 1</li></ul>
+#
+#  Tables:
+#  |= h1 |= h2       ->    <table><tr><th>h1</th><th>h2</th></tr>
+#  |  c1 |  c2             <tr><td>c1</td><td>c2</td></tr></table>
+#
+#  Nowiki (Preformatted):
+#  {{{                     <pre>
+#    ** not bold **          ** not bold **
+#    escaped HTML:   ->      escaped HTML:
+#    <i> test </i>           &lt;i&gt; test &lt;/i&gt;
+#  }}}                     <pre>
+#
+#  {{{ inline\\also }}} -> <tt>inline\\also</tt>
+#
+#  Escape Character:
+#  ~** not bold **    ->    ** not bold **
+#  tilde: ~~          ->    tilde: ~
+#
+#  Paragraphs are separated by other blocks and blank lines.  
+#  Inline markup can usually be combined, overlapped, etc.  List
+#  items and plugin text can span lines.
+#
+# == Extended Markup
+#
+#  In addition to OFFICIAL MARKUP, Text::WikiCreole also supports
+#  the following markup:
+#
+#  Plugins:
+#  << plugin >>        ->    whatever you want (see WikiCreole.creole_plugin)
+#  <<< plugin >>>      ->    whatever you want (see WikiCreole.creole_plugin)
+#      Triple-bracket syntax has priority, in order to allow you to embed
+#      double-brackets in plugins, such as to embed Perl code.
+#
+#  Inline:
+#  ## monospace ##     ->    <tt> monospace </tt>
+#  ^^ superscript ^^   ->    <sup> superscript </sup>
+#  ,, subscript ,,     ->    <sub> subscript </sub>
+#  __ underline __     ->    <u> underline </u>
+#  (TM)                ->    &trade;
+#  (R)                 ->    &reg;
+#  (C)                 ->    &copy;
+#  ...                 ->    &hellip;
+#  --                  ->    &ndash;
+#
+#  Indented Paragraphs:
+#  :this               ->    <div style="margin-left:2em"><p>this
+#  is indented               is indented</p>
+#  :: more indented          <div style="margin-left:2em"><p> more
+#                            indented</div></div>
+#
+#  Definition Lists:
+#  ; Title             ->    <dl><dt>Title</dt>
+#  : item 1 : item 2         <dd>item 1</dd><dd>item 2</dd>
+#  ; Title 2 : item2a        <dt>Title 2</dt><dd>item 2a</dd></dl>
+#
+# == Acknowledgements
+# Most of this code is ported from Jason Burnett's excellent Perl-based
+# converter which can be found here:
+# http://search.cpan.org/~jburnett/Text-WikiCreole/
+# He, in turn, acknowledges the Document::Parser perl module.
+# 
+# Also, some of the tests are taken from Lars Christensen's implementation of
+# the Creole parser.  You can find his code at:
+# http://github.com/larsch/creole/tree/master
+#
+# Other test come from the wikicreole website itself, here:
+# http://www.wikicreole.org/
+
+class WikiCreole
+  
+  # Reads Creole 1.0 markup and return XHTML.
+  #
+  # xhtml = WikiCreole.creole_parse(wiki_creole_markup)
+  def self.creole_parse(s)
+    return "" if s.class.to_s != "String"
+    return "" if s.length < 1
+
+    init
+    return parse(s, :top)
+  end
+  
+  # Creole 1.0 supports two plugin syntaxes: << plugin content >> and
+  # <<< plugin content >>>
+  # 
+  # Write a function that receives the text between the <<>> 
+  # delimiters (not including the delimiters) and 
+  # returns the text to be displayed.  For example, here is a 
+  # simple plugin that converts plugin text to uppercase:
+  #
+  #  uppercase = Proc.new {|s| 
+  #    s.upcase!
+  #    s
+  #  }
+  #  WikiCreole.creole_plugin(uppercase)
+  #
+  # If you do not register a plugin function, plugin markup will be left
+  # as is, including the surrounding << >>.
+  def self.creole_plugin(func)
+    @plugin_function = func
+  end
+
+  # You may wish to customize [[ links ]], such as to prefix a hostname,
+  # port, etc.
+  #
+  # Write a function, similar to the plugin function, which receives the
+  # URL part of the link (with leading and trailing whitespace stripped) 
+  # and returns the customized link.  For example, to prepend 
+  #  http://my.domain/
+  # to pagename:
+  #
+  #  mylink = Proc.new {|s| 
+  #    s = "http://my.domain/" + s
+  #    s
+  #  }
+  #  WikiCreole.creole_link(mylink)
+  def self.creole_link(func)
+    @link_function = func
+  end
+  
+  # Same purpose as creole_link, but for "bare" link markup.  Bare links are
+  # the links which are in the text but not surrounded by brackets.
+  #
+  #  mybarelink = Proc.new {|s| 
+  #    s = s + ".html"
+  #    s
+  #  }
+  #  WikiCreole.creole_barelink(mybarelink)
+  def self.creole_barelink(func)
+    @barelink_function = func
+  end
+
+  # Same purpose as creole_link, but for image URLs.
+  #
+  #  myimg = Proc.new {|s| 
+  #    s = "http://my.domain/" + s
+  #    s
+  #  }
+  #  WikiCreole.creole_img(myimg)
+  def self.creole_img(func)
+    @img_function = func
+  end
+  
+  # If you want complete control over links, rather than just modifying
+  # the URL, register your link markup function with WikiCreole.creole_link()
+  # as above and then call creole_customlinks().  Now your function will receive
+  # the entire link markup chunk, such as <tt>[[ some_wiki_page | page description ]]</tt> 
+  # and must return HTML.
+  #
+  # This has no effect on "bare" link markup, such as
+  #  http://cpan.org
+  def self.creole_customlinks
+    @@chunks_hash[:href][:open] = ""
+    @@chunks_hash[:href][:close] = ""
+    @@chunks_hash[:link][:open] = ""
+    @@chunks_hash[:link][:close] = ""
+    @@chunks_hash[:link].delete(:contains)
+    @@chunks_hash[:link][:filter] = Proc.new {|s| 
+      if @link_function
+        s = @link_function.call(s)
+      end
+      s
+    }
+  end
+
+  # Same purpose as creole_customlinks, but for "bare" link markup.
+  def self.creole_custombarelinks
+    @@chunks_hash[:ilink][:open] = ""
+    @@chunks_hash[:ilink][:close] = ""
+    @@chunks_hash[:ilink][:filter] = Proc.new {|s| 
+      if @barelink_function
+        s = @barelink_function.call(s)
+      end
+      s
+    }
+  end
+
+  # Similar to creole_customlinks, but for images.
+  def self.creole_customimgs
+    @@chunks_hash[:img][:open] = ""
+    @@chunks_hash[:img][:close] = ""
+    @@chunks_hash[:img].delete(:contains)
+    @@chunks_hash[:img][:filter] = Proc.new {|s| 
+      if @img_function
+        s = @img_function.call(s)
+      end
+      s
+    }
+  end
+  
+  # You may wish to customize the opening and/or closing tags
+  # for the various bits of Creole markup.  For example, to
+  # assign a CSS class to list items:
+  #  WikiCreole.creole_tag(:li, :open, "<li class=myclass>")
+  #
+  # Or to see all current tags:
+  #  puts WikiCreole.creole_tag()
+  #
+  # The tags that may be of interest are:
+  #
+  #  br          dd          dl
+  #  dt          em          h1
+  #  h2          h3          h4
+  #  h5          h6          hr 
+  #  ilink       img         inowiki
+  #  ip          li          link
+  #  mono        nowiki      ol
+  #  p           strong      sub
+  #  sup         table       td
+  #  th          tr          u
+  #  ul
+  #
+  # Those should be self-explanatory, except for inowiki (inline nowiki),
+  # ilink (bare links, e.g.
+  #  http://www.cpan.org
+  # and ip (indented paragraph).
+  def self.creole_tag(*args)
+    
+    # I bet a good Ruby hacker would know a way around this little chunk...
+    tag = args.length > 0 ? args[0] : nil
+    type = args.length > 1 ? args[1] : nil
+    text = args.length > 2 ? args[2] : nil
+    
+    if tag.nil?
+      tags = ""
+      for key in @@chunks_hash.keys.collect{|x| x.to_s}.sort
+        key = key.to_sym
+        o = @@chunks_hash[key][:open]
+        c = @@chunks_hash[key][:close]
+        next if o.nil? || !o.index(/</m)
+        o = o.gsub(/\n/m,"\\n")
+        c = c.gsub(/\n/m,"\\n") if c
+        c = "" if c.nil?
+        this_tag = "#{key}: open(#{o}) close(#{c})\n"
+        tags += this_tag
+      end
+      return tags
+    else
+      return if ! type
+      type = type.to_sym
+      return if type != :open && type != :close
+      return if !@@chunks_hash.has_key?(tag)
+      @@chunks_hash[tag][type] = text ? text : ""
+    end
+  end
+  
+  private
+  
+  # characters that may indicate inline wiki markup
+  @@specialchars = ['^', '\\', '*', '/', '_', ',', '{', '[', 
+                    '<', '~', '|', "\n", '#', ':', ';', '(', '-', '.']
+                  
+  # plain characters - auto-generated below (ascii printable minus @specialchars)
+  @@plainchars = []
+
+  # non-plain text inline widgets
+  @@inline = %w{strong em br esc img link ilink inowiki
+                sub sup mono u plug plug2 tm reg copy ndash ellipsis amp}
+            
+  @@all_inline = [@@inline, 'plain', 'any'].flatten # including plain text
+
+  @@blocks = %w{h1 h2 h3 hr nowiki h4 h5 h6 ul ol table p ip dl plug plug2 blank}
+  
+  # handy - used several times in %chunks
+  @@eol = '(?:\n|$)'; # end of line (or string)
+  
+  @plugin_function = nil
+  @barelink_function = nil
+  @link_function = nil
+  @img_function = nil
+  
+  @is_initialized = false
+
+  @@chunks_hash = {
+    :top => {
+       :contains => @@blocks,
+    },
+    :blank => {
+      :curpat => "(?= *#{@@eol})",
+      :fwpat => "(?=(?:^|\n) *#{@@eol})",
+      :stops => '(?=\S)',
+      :hint => ["\n"],
+      :filter => Proc.new { "" }, # whitespace into the bit bucket
+      :open => "", :close => "",
+    },
+    :p => {
+      :curpat => '(?=.)',
+      :stops => ['blank', 'ip', 'h', 'hr', 'nowiki', 'ul', 'ol', 'dl', 'table'],
+      :hint => @@plainchars,
+      :contains => @@all_inline,
+      :filter => Proc.new {|s| s.chomp },
+      :open => "<p>", :close => "</p>\n\n",
+    },
+    :ip => {
+      :curpat => '(?=:)',
+      :fwpat => '\n(?=:)',
+      :stops => ['blank', 'h', 'hr', 'nowiki', 'ul', 'ol', 'dl', 'table'],
+      :hint => [':'],
+      :contains => ['p', 'ip'],
+      :filter => Proc.new {|s|
+        s.sub!(/:/, '')
+        s.sub!(/\n:/m, "\n")
+        s
+      },
+      :open => "<div style=\"margin-left: 2em\">", :close => "</div>\n",
+    },
+    :dl => {
+      :curpat => '(?=;)',
+      :fwpat => '\n(?=;)',
+      :stops => ['blank', 'h', 'hr', 'nowiki', 'ul', 'ol', 'table'],
+      :hint => [';'],
+      :contains => ['dt', 'dd'],
+      :open => "<dl>\n", :close => "</dl>\n",
+    },
+    :dt => {
+      :curpat => '(?=;)',
+      :fwpat => '\n(?=;)',
+      :stops => '(?=:|\n)',
+      :hint => [';'],
+      :contains => @@all_inline,
+      :filter => Proc.new {|s|
+        s.sub!(/^;\s*/, '')
+        s
+      },
+      :open => "  <dt>", :close => "</dt>\n",
+    },
+    :dd => {
+      :curpat => '(?=\n|:)',
+      :fwpat => '(?:\n|:)',
+      :stops => '(?=:)|\n(?=;)',
+      :hint => [':', "\n"],
+      :contains => @@all_inline,
+      :filter => Proc.new {|s|
+        s.sub!(/(?:\n|:)\s*/m, '')
+        s.sub!(/\s*$/m, '')
+        s
+      },
+      :open => "    <dd>", :close => "</dd>\n",
+    },
+    :table => {
+      :curpat => '(?= *\|.)',
+      :fwpat => '\n(?= *\|.)',
+      :stops => '\n(?= *[^\|])',
+      :contains => ['tr'],
+      :hint => ['|', ' '],
+      :open => "<table>\n", :close => "</table>\n\n",
+    },
+    :tr => {
+      :curpat => '(?= *\|)',
+      :stops => '\n',
+      :contains => ['td', 'th'],
+      :hint => ['|', ' '],
+      :filter => Proc.new {|s|
+        s.sub!(/^ */, '')
+        s.sub!(/\| *$/, '')
+        s
+      },
+      :open => "    <tr>\n", :close => "    </tr>\n",
+    },
+    :td => {
+      :curpat => '(?=\|[^=])',
+      # this gnarly regex fixes ambiguous '|' for links/imgs/nowiki in tables
+      :stops => '[^~](?=\|(?!(?:[^\[]*\]\])|(?:[^\{]*\}\})))',
+      :contains => @@all_inline,
+      :hint => ['|'],
+      :filter => Proc.new {|s|
+        s.sub!(/^ *\| */, '')
+        s.sub!(/\s*$/m, '')
+        s
+      },
+      :open => "        <td>", :close => "</td>\n",
+    },
+    :th => {
+      :curpat => '(?=\|=)',
+      # this gnarly regex fixes ambiguous '|' for links/imgs/nowiki in tables
+      :stops => '[^~](?=\|(?!(?:[^\[]*\]\])|(?:[^\{]*\}\})))',
+      :contains => @@all_inline,
+      :hint => ['|'],
+      :filter => Proc.new {|s|
+        s.sub!(/^ *\|= */, '')
+        s.sub!(/\s*$/m, '')
+        s
+      },
+      :open => "        <th>", :close => "</th>\n",
+    },
+    :ul => {
+      :curpat => '(?=(?:`| *)\*[^\*])',
+      :fwpat => '(?=\n(?:`| *)\*[^\*])',
+      :stops => ['blank', 'ip', 'h', 'nowiki', 'li', 'table', 'hr', 'dl'],
+      :contains => ['ul', 'ol', 'li'],
+      :hint => ['*', ' '],
+      :filter => Proc.new {|s|
+        s = strip_list(s)
+        s
+      },
+      :open => "<ul>\n", :close => "</ul>\n",
+    },
+    :ol => {
+      :curpat => '(?=(?:`| *)\#[^\#])',
+      :fwpat => '(?=\n(?:`| *)\#[^\#])',
+      :stops => ['blank', 'ip', 'h', 'nowiki', 'li', 'table', 'hr', 'dl'],
+      :contains => ['ul', 'ol', 'li'],
+      :hint => ['#', ' '],
+      :filter => Proc.new {|s|
+        s = strip_list(s)
+        s
+      },
+      :open => "<ol>\n", :close => "</ol>\n",
+    },
+    :li => {
+      :curpat => '(?=`[^\*\#])',
+      :fwpat => '\n(?=`[^\*\#])',
+      :stops => '\n(?=`)',
+      :hint => ['`'],
+      :filter => Proc.new {|s|
+        s.sub!(/` */, '')
+        s.chomp!
+        s
+      },
+      :contains => @@all_inline,
+      :open => "    <li>", :close => "</li>\n",
+    },
+    :nowiki => {
+      :curpat => '(?=\{\{\{ *\n)',
+      :fwpat => '\n(?=\{\{\{ *\n)',
+      :stops => "\n\\}\\}\\} *#{@@eol}",
+      :hint => ['{'],
+      :filter => Proc.new {|s|
+        s[0,3] = ''
+        s.sub!(/\}{3}\s*$/, '')
+        s.gsub!(/&/, '&amp;')
+        s.gsub!(/</, '&lt;')
+        s.gsub!(/>/, '&gt;')
+        s
+      },
+      :open => "<pre>", :close => "</pre>\n\n",
+    },
+    :hr => {
+      :curpat => "(?= *-{4,} *#{@@eol})",
+      :fwpat => "\n(?= *-{4,} *#{@@eol})",
+      :hint => ['-', ' '],
+      :stops => @@eol,
+      :open => "<hr />\n\n", :close => "",
+      :filter => Proc.new { "" } # ----- into the bit bucket
+    },
+    :h => { :curpat => '(?=(?:^|\n) *=)' }, # matches any heading
+    :h1 => {
+      :curpat => '(?= *=[^=])',
+      :hint => ['=', ' '], 
+      :stops => '\n',
+      :contains => @@all_inline,
+      :open => "<h1>", :close => "</h1>\n\n",
+      :filter => Proc.new {|s|
+        s = strip_leading_and_trailing_eq_and_whitespace(s)
+        s
+      },
+    },
+    :h2 => {
+      :curpat => '(?= *={2}[^=])',
+      :hint => ['=', ' '], 
+      :stops => '\n',
+      :contains => @@all_inline,
+      :open => "<h2>", :close => "</h2>\n\n",
+      :filter => Proc.new {|s|
+        s = strip_leading_and_trailing_eq_and_whitespace(s)
+        s
+      },
+    },
+    :h3 => {
+      :curpat => '(?= *={3}[^=])',
+      :hint => ['=', ' '], 
+      :stops => '\n',
+      :contains => @@all_inline,
+      :open => "<h3>", :close => "</h3>\n\n",
+      :filter => Proc.new {|s|
+        s = strip_leading_and_trailing_eq_and_whitespace(s)
+        s
+      },
+    },
+    :h4 => {
+      :curpat => '(?= *={4}[^=])',
+      :hint => ['=', ' '], 
+      :stops => '\n',
+      :contains => @@all_inline,
+      :open => "<h4>", :close => "</h4>\n\n",
+      :filter => Proc.new {|s|
+        s = strip_leading_and_trailing_eq_and_whitespace(s)
+        s
+      },
+    },
+    :h5 => {
+      :curpat => '(?= *={5}[^=])',
+      :hint => ['=', ' '], 
+      :stops => '\n',
+      :contains => @@all_inline,
+      :open => "<h5>", :close => "</h5>\n\n",
+      :filter => Proc.new {|s|
+        s = strip_leading_and_trailing_eq_and_whitespace(s)
+        s
+      },
+    },
+    :h6 => {
+      :curpat => '(?= *={6,})',
+      :hint => ['=', ' '], 
+      :stops => '\n',
+      :contains => @@all_inline,
+      :open => "<h6>", :close => "</h6>\n\n",
+      :filter => Proc.new {|s|
+        s = strip_leading_and_trailing_eq_and_whitespace(s)
+        s
+      },
+    },
+    :plain => {
+      :curpat => '(?=[^\*\/_\,\^\\\\{\[\<\|])',
+      :stops => @@inline,
+      :hint => @@plainchars,
+      :open => '', :close => ''
+    },
+    :any => { # catch-all
+      :curpat => '(?=.)',
+      :stops => @@inline,
+      :open => '', :close => ''
+    },
+    :br => {
+      :curpat => '(?=\\\\\\\\)',
+      :stops => '\\\\\\\\',
+      :hint => ['\\'],
+      :filter => Proc.new { "" },
+      :open => '<br />', :close => '',
+    },
+    :esc => {
+      :curpat => '(?=~[\S])',
+      :stops => '~.',
+      :hint => ['~'],
+      :filter => Proc.new {|s|
+        s.sub!(/^./m, '')
+        s
+      },
+      :open => '', :close => '',
+    },
+    :inowiki => {
+      :curpat => '(?=\{{3}.*?\}*\}{3})',
+      :stops => '.*?\}*\}{3}',
+      :hint => ['{'],
+      :filter => Proc.new {|s|
+        s[0,3] = ''
+        s.sub!(/\}{3}\s*$/, '')
+        s.gsub!(/&/, '&amp;')
+        s.gsub!(/</, '&lt;')
+        s.gsub!(/>/, '&gt;')
+        s
+      },
+      :open => "<tt>", :close => "</tt>",
+    },
+    :plug => {
+      :curpat => '(?=\<{3}.*?\>*\>{3})',
+      :stops => '.*?\>*\>{3}',
+      :hint => ['<'],
+      :filter => Proc.new {|s|
+        s[0,3] = ''
+        s.sub!(/\>{3}$/, '')
+        if !@plugin_function.nil?
+          s = @plugin_function.call(s)
+        else
+          s = "<<<#{s}>>>"
+        end
+        s
+      },
+      :open => "", :close => "",
+    },
+    :plug2 => {
+      :curpat => '(?=\<{2}.*?\>*\>{2})',
+      :stops => '.*?\>*\>{2}',
+      :hint => ['<'],
+      :filter => Proc.new {|s|
+        s[0,2] = ''
+        s.sub!(/\>{2}$/, '')
+        if !@plugin_function.nil?
+          s = @plugin_function.call(s)
+        else
+          s = "<<#{s}>>"
+        end
+        s
+      },
+      :open => "", :close => "",
+    },
+    :ilink => {
+      :curpat => '(?=(?:https?|ftp):\/\/)',
+      # This following is the [:punct:] character class with the / and ? removed
+      # so that URLs like http://www.somesite.com/ will match the trailing
+      # slash.  URLs with a trailing ? will also work.  Trailing ? is sometimes
+      # used to ensure that browsers don't cache the page.
+      :stops => '(?=[!"#$%&\'()*+,-.:;<=>@\[\\]^_`{|}~]?(?:\s|$))',
+      :hint => ['h', 'f'],
+      :filter => Proc.new {|s|
+        s.sub!(/^\s*/, '')
+        s.sub!(/\s*$/, '')
+        if !@barelink_function.nil?
+          s = @barelink_function.call(s)
+        end  
+        s = "href=\"#{s}\">#{s}"
+        s
+      },
+      :open => "<a ", :close=> "</a>",
+    },
+    :link => {
+      :curpat => '(?=\[\[[^\n]+?\]\])',
+      :stops => '\]\]',
+      :hint => ['['],
+      :contains => ['href', 'atext'],
+      :filter => Proc.new {|s|
+        s[0,2] = ''
+        s[-2,2] = ''
+        s += "|#{s}" if ! s.index(/\|/) # text = url unless given
+        s      
+      },
+      :open => "<a ", :close => "</a>",
+    },
+    :href => {
+      :curpat => '(?=[^\|])',
+      :stops => '(?=\|)',
+      :filter => Proc.new {|s|
+        s.sub!(/^\s*/, '')
+        s.sub!(/\s*$/, '')
+        if !@link_function.nil?
+          s = @link_function.call(s)
+        end
+        s
+      },
+      :open => 'href="', :close => '">',
+    },
+   :atext => {
+      :curpat => '(?=\|)',
+      :stops => '\n',
+      :hint => ['|'],
+      :contains => @@all_inline,
+      :filter => Proc.new {|s|
+        s.sub!(/^\|\s*/, '')
+        s.sub!(/\s*$/, '')
+        s
+      },
+      :open => '', :close => '',
+   },
+   :img => {
+      :curpat => '(?=\{\{[^\{][^\n]*?\}\})',
+      :stops => '\}\}',
+      :hint => ['{'],
+      :contains => ['imgsrc', 'imgalt'],
+      :filter => Proc.new {|s|
+        s[0,2] = ''
+        s.sub!(/\}\}$/, '')
+        s
+      },
+      :open => "<img ", :close => " />",
+   },
+   :imgalt => {
+      :curpat => '(?=\|)',
+      :stops => '\n',
+      :hint => ['|'],
+      :filter => Proc.new {|s|
+        s.sub!(/^\|\s*/, '')
+        s.sub!(/\s*$/, '')
+        s
+      },
+      :open => ' alt="', :close => '"',
+   },
+   :imgsrc => {
+      :curpat => '(?=[^\|])',
+      :stops => '(?=\|)',
+      :filter => Proc.new {|s|
+        s.sub!(/^\|\s*/, '')
+        s.sub!(/\s*$/, '')
+        if !@img_function.nil?
+          s = @img_function.call(s)
+        end
+        s
+      },
+      :open => 'src="', :close => '"',
+   },
+    :strong => {
+      :curpat => '(?=\*\*)',
+      :stops => '\*\*.*?\*\*',
+      :hint => ['*'],
+      :contains => @@all_inline,
+      :filter => Proc.new {|s|
+        s[0,2] = ''
+        s.sub!(/\*\*$/, '')
+        s
+      },
+      :open => "<strong>", :close => "</strong>",
+    },
+    :em => {
+      # This could use a negative lookback assertion to let you know whether
+      # it's part of a URL or not.  That would be helpful if the URL had been
+      # escaped.  Currently, it will just become italic after the // since 
+      # it didn't process the URL.
+      :curpat => '(?=\/\/)',
+      # Removed a negative lookback assertion (?<!:) from the Perl version
+      # and replaced it with [^:]  Not sure of the consequences, however, as
+      # of this version, Ruby does not have negative lookback assertions, so
+      # I had to do it.
+      :stops => '\/\/.*?[^:]\/\/',
+      :hint => ['/'],
+      :contains => @@all_inline,
+      :filter => Proc.new {|s|
+        s[0,2] = ''
+        s.sub!(/\/\/$/, '')
+        s
+      },
+      :open => "<em>", :close => "</em>",
+    },
+    :mono => {
+      :curpat => '(?=\#\#)',
+      :stops => '\#\#.*?\#\#',
+      :hint => ['#'],
+      :contains => @@all_inline,
+      :filter => Proc.new {|s|
+        s[0,2] = ''
+        s.sub!(/\#\#$/, '')
+        s
+      },
+      :open => "<tt>", :close => "</tt>",
+    },
+    :sub => {
+      :curpat => '(?=,,)',
+      :stops => ',,.*?,,',
+      :hint => [','],
+      :contains => @@all_inline,
+      :filter => Proc.new {|s|
+        s[0,2] = ''
+        s.sub!(/\,\,$/, '')
+        s
+      },
+      :open => "<sub>", :close => "</sub>",
+    },
+    :sup => {
+      :curpat => '(?=\^\^)',
+      :stops => '\^\^.*?\^\^',
+      :hint => ['^'],
+      :contains => @@all_inline,
+      :filter => Proc.new {|s|
+        s[0,2] = ''
+        s.sub!(/\^\^$/, '')
+        s
+      },
+      :open => "<sup>", :close => "</sup>",
+    },
+    :u => {
+      :curpat => '(?=__)',
+      :stops => '__.*?__',
+      :hint => ['_'],
+      :contains => @@all_inline,
+      :filter => Proc.new {|s|
+        s[0,2] = ''
+        s.sub!(/__$/, '')
+        s
+      },
+      :open => "<u>", :close => "</u>",
+    },
+    :amp => {
+      :curpat => '(?=\&(?!\w+\;))',
+      :stops => '.',
+      :hint => ['&'],
+      :filter => Proc.new { "&amp;" },
+      :open => "", :close => "",
+    },
+    :tm => {
+      :curpat => '(?=\(TM\))',
+      :stops => '\(TM\)',
+      :hint => ['('],
+      :filter => Proc.new { "&trade;" },
+      :open => "", :close => "",
+    },
+    :reg => {
+      :curpat => '(?=\(R\))',
+      :stops => '\(R\)',
+      :hint => ['('],
+      :filter => Proc.new { "&reg;" },
+      :open => "", :close => "",
+    },
+    :copy => {
+      :curpat => '(?=\(C\))',
+      :stops => '\(C\)',
+      :hint => ['('],
+      :filter => Proc.new { "&copy;" },
+      :open => "", :close => "",
+    },
+    :ndash => {
+      :curpat => '(?=--)',
+      :stops => '--',
+      :hint => ['-'],
+      :filter => Proc.new { "&ndash;" },
+      :open => "", :close => "",
+    },
+    :ellipsis => {
+      :curpat => '(?=\.\.\.)',
+      :stops => '\.\.\.',
+      :hint => ['.'],
+      :filter => Proc.new { "&hellip;" },
+      :open => "", :close => "",
+    },
+  }
+  
+  def self.strip_leading_and_trailing_eq_and_whitespace(s)
+    s.sub!(/^\s*=*\s*/, '')
+    s.sub!(/\s*=*\s*$/, '')
+    return s
+  end
+
+  def self.strip_list(s)
+    s.sub!(/(?:`*| *)[\*\#]/, '`')
+    s.gsub!(/\n(?:`*| *)[\*\#]/m, "\n`")
+    return s
+  end
+  
+  def self.filter_string_x_with_chunk_filter_y(str, chunk)
+    return @@chunks_hash[chunk][:filter].call(str)
+  end
+  
+  def self.parse(tref, chunk)
+  
+    sub_chunk = nil
+    pos = 0
+    last_pos = 0
+    html = ""
+
+    loop do
+
+      if sub_chunk # we've determined what type of sub_chunk this is
+        
+        if sub_chunk == :dd
+          # Yuck... I don't exactly understand why I need this section, but
+          # without it the parser will go into an infinite loop on the :dd's in
+          # the test suite.  Please, if you're a most excellent Ruby hacker,
+          # find the issue, clean this up, and remove the comment here, m'kay?
+          
+          while tref.index(Regexp.compile('\G.*' + @@chunks_hash[sub_chunk][:delim], Regexp::MULTILINE), pos)
+            end_of_match = Regexp.last_match.end(0)
+            if end_of_match == pos
+              break
+            else
+              pos = end_of_match
+            end
+          end
+
+          if pos == last_pos
+            pos = tref.length
+          end
+        else
+          # This is a little slower than it could be.  The delim should be
+          # pre-compiled, but see the issue in the comment above.
+          if tref.index(Regexp.compile(@@chunks_hash[sub_chunk][:delim], Regexp::MULTILINE), pos)
+            pos = Regexp.last_match.end(0)
+          else 
+            pos = tref.length
+          end
+        end
+
+        html += @@chunks_hash[sub_chunk][:open]
+
+        t = tref[last_pos, pos - last_pos] # grab the chunk
+
+        if @@chunks_hash[sub_chunk].has_key?(:filter)   # filter it, if applicable
+          t = @@chunks_hash[sub_chunk][:filter].call(t)
+        end
+        
+        last_pos = pos  # remember where this chunk ends (where next begins)
+        
+        if t && @@chunks_hash[sub_chunk].has_key?(:contains)  # if it contains other chunks...
+          html += parse(t, sub_chunk)         #    recurse.
+        else
+          html += t                    # otherwise, print it
+        end
+        
+        html += @@chunks_hash[sub_chunk][:close]       # print the close tag
+        
+      end
+
+      if pos && pos == tref.length # we've eaten the whole string
+        break
+      else ## more string to come
+        sub_chunk = get_sub_chunk_for(tref, chunk, pos)
+      end
+      
+    end
+    
+    return html
+  end
+  
+  def self.get_sub_chunk_for(tref, chunk, pos)
+
+    first_char = tref[pos, 1] # get a hint about the next chunk
+    for chunk_hinted_at in @@chunks_hash[chunk][:calculated_hint_array_for][first_char].to_a
+      #puts "trying hint #{chunk_hinted_at} for -#{first_char}- on -" + tref[pos, 2] + "-\n"
+      if tref.index(@@chunks_hash[chunk_hinted_at][:curpatcmp], pos) # hint helped id the chunk
+        return chunk_hinted_at
+      end
+    end
+
+    # the hint didn't help. Check all the chunk types which this chunk contains
+    for contained_chunk in @@chunks_hash[chunk][:contains].to_a
+      #puts "trying contained chunk #{contained_chunk} on -" + tref[pos, 2] + "- within chunk #{chunk.to_s}\n"
+      if tref.index(@@chunks_hash[contained_chunk.to_sym][:curpatcmp], pos) # found one
+        return contained_chunk.to_sym
+      end
+    end
+    
+    return nil
+  end
+  
+  # compile a regex that matches any of the patterns that interrupt the
+  # current chunk.
+  def self.delim(chunk)
+    chunk = @@chunks_hash[chunk]
+    if chunk[:stops].class.to_s == "Array"
+      regex = ''
+      for stop in chunk[:stops]
+        stop = stop.to_sym
+        if @@chunks_hash[stop].has_key?(:fwpat)
+          regex += @@chunks_hash[stop][:fwpat] + "|"
+        else
+          regex += @@chunks_hash[stop][:curpat] + "|"
+        end
+      end
+      regex.chop!
+      return regex
+    else
+      return chunk[:stops]
+    end
+  end
+  
+  # one-time optimization of the grammar - speeds the parser up a ton
+  def self.init 
+    return if @is_initialized
+
+    @is_initialized = true
+
+    # build an array of "plain content" characters by subtracting @specialchars
+    # from ascii printable (ascii 32 to 126)
+    for charnum in 32..126 do
+      char = charnum.chr
+      if @@specialchars.index(char).nil?
+        @@plainchars << char
+      end
+    end
+
+    # precompile a bunch of regexes 
+    for k in @@chunks_hash.keys do
+      c = @@chunks_hash[k]
+      if c.has_key?(:curpat)
+        c[:curpatcmp] = Regexp.compile('\G' + c[:curpat], Regexp::MULTILINE)
+      end
+      
+      if c.has_key?(:stops)
+        c[:delim] = delim(k)
+      end
+      
+      if c.has_key?(:contains) # store hints about each chunk to speed id
+        c[:calculated_hint_array_for] = {}
+        
+        for ct in c[:contains]
+          ct = ct.to_sym
+          
+          if @@chunks_hash[ct].has_key?(:hint)
+            for hint in @@chunks_hash[ct][:hint]
+              if !c[:calculated_hint_array_for].has_key?(hint)
+                c[:calculated_hint_array_for][hint] = []
+              end
+              c[:calculated_hint_array_for][hint] << ct
+            end
+          end
+
+        end
+      end
+    end
+    
+  end
+  
+  
+
+end