Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tree: cb40118467
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 139 lines (113 sloc) 6.322 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138
=== Flower: XML Application Languages ===

Flower is a library for building and using XML Application Languages.
An XML Application Language can be anything that takes an XML document,
and parses it using a set of data. It's perfect for creating template engines,
custom XML syntax, and much more, all using pure XML as its input and output
formats.

Flower was originally written to create an implementation of the TAL and METAL
template engines from Zope. Flower's name was originally a play on the Perl 5
Petal library. Since then, Flower has outgrown its original scope, bringing
in further ideas from Template::TAL, PHPTAL, and some of my own custom XML
concepts. The original TAL/METAL/TALES parsers are still included, and can
be easily used by using Flower::TAL, which is included (see below.)

= Requirements =

 - Rakudo Perl 6
   http://rakudo.org/
   NOTE: Unlike most of my libraries, Exemel and Flower only work on the
   "ng" branch of Rakudo, and not the "nom" branch. Once grammars/regexes are
   working fully in "nom", I'll make sure both libraries work on "nom" again.

 - Exemel
   The XML library that powers Flower.
   http://github.com/supernovus/exemel/

= Optional libraries:

 - DateTime::Utils
   Needed if you want to use Flower::TAL::TALES::Date
   which is included in Flower::TAL's list of plugins.
   http://github.com/supernovus/temporal-utils/

=== Flower::TAL ===

This is an easily loadable library that extends Flower and automatically
loads the Flower::TAL::TAL, Flower::TAL::METAL application languages
by default, and offers the ability to easily load plugins for the
Flower::TAL::TALES attribute parser (used by Flower::TAL::TAL)

= Major Differences from Petal =

 * The default local namespace is 'tal', and to override it, you must
   declare http://xml.zope.org/namespaces/tal instead of the Petal namespace.
 * Flower can use template strings instead of requiring files.
 * Flower does not support the multiple template files based on language.
 * Adding custom modifiers is completely different in Flower.
 * There is NO support for anything but well-formed XML.
   There is no equivelant to the Petal::Parser::HTB, and no plans for one.
   Use well-formed XML, it's just better.
 * Flower supports tal:block elements, as per the PHPTAL project.
 * While you can use the 'structure' keyword, it's not really needed.
   If you want an unescaped XML structure for a replacement, send an
   Exemel object (any class other than Document) and it will be added to
   the XML tree. Send an array of Exemel objects, and they will additionally
   be parsed for TAL statements.
 * Nested repeats cannot use the same attribute name, it will get clobbered.
 * The built-in repeat object is implemented as per the Zope/PHPTAL, not
   the Petal version. Note: it does not support the 'letter' or 'Letter'
   attributes, but instead has some new methods that take paramters:
     'every xx' the number (not the index) is divisible by xx.
     'skip xx' the number is not divisible by xx.
     'gt xx' the number is greater than xx.
     'lt xx' the number is less than xx.
     'eq xx' the number is equal to xx.
     'ne xx' the number is not equal to xx.
 * I'm not sure how Petal, PHPTAL or Zope deal with TAL attributes in the
   root element (the top-most element of the document), but to avoid death,
   destruction and mayhem, Flower only processes 'define', 'attributes'
   and 'content' tags on the root element. The rest of the tags are only
   processed on children of the root.

The above list will be updated as this project is developed, as I'm sure
other changes will be introduced that will be a gotchya for users of Petal,
Zope or PHPTAL.

= Flower::TAL Plugins =

Inspired by Petal::Utils, Flower includes a bunch of libraries in the
Flower::TAL::TALES:: namespace. These are also available using Flower::TAL's
add-tales() method.

  - Text, same as the :text set from Petal::Utils
    lc: make the string lowercase.
    uc: make the string uppercase.
    ucfirst: make the first letter of the string uppercase.
    substr: extract a portion of the string.
    printf: format a string or object in a specified way.
  - List, similar to the :list set from Petal::Utils.
    group: turns a flat Array into a nested Array, where each inner
             Array has a set number of elements in it.
    sort: sort the array using the default sort algorithm.
    limit: only return the first number of items from the list.
    shuffle: shuffle the list into a random order.
    pick: pick a set number of items randomly from the list.
    reverse: reverse the contents of the list.
  - Date, similar to the :date set from Petal::Utils, using on DateTime::Utils
    date: Builds a DateTime object using specified paramters.
    time: Builds a DateTime object from a Unix epoch.
    strftime: Displays a date/time string in a specified format.
    rfc: A modifier specifically for use with strftime, as the format.
    now: A modifier specifically for use with strftime, as the object.
  - Debug, similar to :debug set from Petal::Utils.
    dump: modifier spits out the .perl representation of the object.
    what: modifier spits out the class name of the object.

In addition, the following sets are planned for inclusion very soon:

  - Logic, similar to the :logic set from Petal::Utils
  - Hash, same as the :hash set from Petal::Utils

The syntax for the Flower::TAL plugins is based on the modifiers from
Petal::Utils, but extended to use the Flower-specific extensions (the
same method that is used to parse method call parameters in queries.)
As is obvious, the syntax is not always the same, and not all of the
modifiers are the same.

Full documentation for the usage of Flower and the Flower::Utils modifiers
will be included in the doc/ folder in an upcoming release, until then
there are comments in the libraries, and test files in t/ that show the
proper usage.

The URI set from Petal::Utils is not planned for inclusion,
feel free to write it if you need it.
I'm sure new exciting libraries will be made adding onto these.

=== Author ===

Timothy Totten
http://huri.net/
http://github.com/supernovus/

=== License ===

Artistic License 2.0
http://www.perlfoundation.org/artistic_license_2_0

Something went wrong with that request. Please try again.