From: "Victor \"Zverok\" Shepelev" <vshepelev@...>
Date: 2007-09-14T10:39:14+09:00
Subject: [ANN] uniforma-0.0.1 - converter for text formats

Hi all.

I'm pleased to announce 0.0.1 (aka "early adopters only" release) of my
Uniforma library.

It's here: http://rubyforge.org/projects/uniforma/

== What is it?

Library for parsing "simple text" formats (RD, Textile, Markdown, etc.) and
generating output in various formats (including simple text, html/xml and
more complex ones). 

The heart of the library is two DSLs - for defining parsers and generators. 

== Why?

1. Preparing "one more serious library"'s documentation, I've found a
dillema: write it in RD? (for auto-generate all with RDoc) or Trac's wiki
format? (for uploading to Trac site) or Textile? (for once uploading to
stand-alone site) So I've decided to do conversion library/tool. 

2. I'm using RedCloth (Textile) for all my works, and trying to patch it for
my needs, I've found it's a mess. I just need to have separate clear
description of "how is it parsed" and "how is it generated" aspects. 

3. For my journalism, I need MS Word output (I have no fun to do text
editing in MS Word, but ability to generate it is a must). Now I use
"Textile=>(RedCloth)=>HTML=>`winword mytext.html`" scheme, which have
several flaws. I want be able to easy define MS Word generator (using
win32ole, of course, no hand-made heroism).

== Show. Me. The. Code.

Usage:

 puts Uniforma::textile('*some text* "with
links":http://google.com.').to_html_string

output:
 <html><body>
 <p><b>some text</b> <a href='http://google.com'>with links</a>.</p>
 </body></html>


Defining parsers:

---
module Uniforma::Parsers
class Textile < LineParser
  definition do
    .... 
    #how to parse some line
    ....
    line /^h(\d+)\.\s+/ do para(:heading, :level => @_1.to_i) end
    ....
    #how to parse inline formatting:
    inline /__(.+?)__/, :italic
  end
end
end
---

Defining generators

---
module Uniforma::Generators
class HtmlString < TextGenerator
  definition do
    ...
    #what to place around some "paragraph type"
    around(:heading)  {|p| i = p.level; ["<h#{i}>", "</h#{i}>\n"]}
    ...
 
    #what to place around some "inline markup type"
    around(:italic)     {["<i>", "</i>"]}
  end
end
end
---

Uniforma is smart enough to allow:
* non-line based formats parsers (in fact, it also has one "toy" parser for
HTML, which even works! on not-very-complex HTML documents)
* non-text format generators (I'm working on PDF and MSWord generators. It's
not very hard to define with Uniforma)

== Important notes about current release

* This release shamelessly includes htmlentities library by Paul Battley[1],
without even notice it in license files. It is subject to change ASAP.

* It's really "early adopters" release. Almost no docs, and very, very poor
tests. But it shows an idea and is a base for further work.

* This release include parsers for: Textile, RD, HTML and generators for:
BBcode, RD, HTML. All of them are incomplete :) but tend to work.

* I'd want to hear opinions about whether DSLs for parser/generator looks
"right" from point-of-view of a) native English speakers and b) real Ruby
ninja. You can examine my parsers in lib/uniforma/parsers/ and generators in
lib/uniforma/generators/


Again, the library is here: http://rubyforge.org/projects/uniforma/

Thanx.

Zverok.

1:http://rubyforge.org/projects/htmlentities/