The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Text::UberText::Overview - General Documentation

HOWTO

How to I create or designate a namespace?

A namespace is two or more words seperated by periods, like "uber.loop", or "acme.database.inventory". All namespaces are in lowercase.

If you do not plan on publishing your code, feel free to use any namespace you want, except the "uber.*" namespace.

If you do want to publish your code, you will need to make a name that is guaraunteed to be unique. There is no standard convention for namespaces, and I'm not even sure if there ever will be one. For now, I would recommend that all of your namespaces start with your organizational id, or perhaps your CPAN id.

QUESTIONS

Can you draw out how the UberText objects work?

1. At Text::UberText initialization

    a. Text::UberText::Log is created.

    b. Text::UberText::Dispatch is created.

    c. Text::UberText::Parser is created.

2. When a document is read and parsed

    a. Text::UberText::Parser creates Text::UberText::Tree.

    b. Parser reads input and breaks it apart into text and commands.

    c. When a command or a full block of text is encountered, Parser creates a Text::UberText::Node::Command or Text::UberText::Node::Text object and passes it on to the Tree.

    d. The Node object runs the process() method which does preliminary cleanup of the input.

3. When the tree is run

    a. The Tree object goes through every Node that has a parent of 0.

    b. The Tree object calls the run() method for that node.

    c. The Node object refers back to the dispatch table to find which object method to run.

    d. The Dispatch object runs the code using the Node data, and passes the output back to the Node object.

4. When the output is displayed

    a. The tree object goes through ever Node that has a parent of 0.

    b. The tree object calls the outout() method for that node.

    c. The output is strung together and returned to the caller.

Why create this? Why not just use MASON or Text::Template?

Text::UberText was designed with several goals in mind. The first goal was to create a template language that was easy to use and yet powerful enough to be useful.

Text::UberText can create an abstract level between documents and program code. Someone writing a document using UberText doesn't need to know how to program, which in turn means the programmer doesn't need to write the UberText document. However, the programmer and the document writer do need to plan out their namespace and command schema beforehand.

Another benefit of this layer of abstraction is that it opens up the possibilities of using other programming languages. If someone wants to create a Text::UberText processor in Java or Python, they are more than welcome to.

MASON and Text::Template are excellent template engines. The downside is that they quickly fall back on their ability to embed Perl code. In some applications it may not be practical to embed raw program code.

So why not use XML?

XML documents are XML documents. UberText documents can be anything. UberText can be mixed in with raw PostScript, plain text, HTML (or even XML), or LaTex. If you don't want to create a whole XML document just to generate dymanic content in one of these output formats, consider using UberText.

There are other differences, like the ability to have options that don't have values passed to them, there is no need to self-close non-structured tags, but the most important one is probably the ability to put UberText tags within the values of UberText tag options.

Why can't I use the uber.* namespace?

I want to keep the "uber.*" namespace in my control so I can add more public routines to UberText down the road.

What's the inspiration for the command format?

I tried to get the command language to look very similar to Objective-C.

Is there a difference between parenthesis and double quotes for parameter arguments?

No, it's just semantics. Some people would prefer to use double quotes to represent strings, and use parenthesis to represents expressions. There is no difference between them when it comes to processing.

Any good examples?

Examples are a work in progress. For now I'd recommend looking over the source code.

Do I have to rewrite my entire module just to use UberText?

No. When the Dispatch module is passed your module or object, it needs to be able to invoke the uberText() method. That method will return the object the Dispatch module needs, the namespace, and the dispatch table. So the object returned from uberText() can be different from the one you passed to the Dispatch table.

If you have a complex module named Widgets::Billing, you can create a whole new module (maybe Widgets::Billing::UberText) that handles all the UberText command tags.

AUTHOR

Chris Josephes <cpj1@visi.com>

COPYRIGHT

Copyright 2002, Chris Josephes. All rights reserved. This module is free software. It may be used, redistributed, and/or modified under the same terms as Perl itself.