view release on metacpan or  search on metacpan

misc/Text-Embed.html  view on Meta::CPAN

<p>
</p>
<h3><a name="stage_1__parsing">Stage 1: Parsing</a></h3>
<p>By default, <strong>Text::Embed</strong> uses similar syntax to the __DATA__ token to 
seperate segments - a line consisting of two underscores surrounding an
identifier. Of course, a suitable syntax depends on the text being embedded.</p>
<p>A REGEX or CODE reference can be passed as the first argument - in order 
to gain finer control of how __DATA__ is parsed:</p>
<dl>
<dt><strong><a name="item_regex">REGEX</a></strong><br />
</dt>
<dd>
<pre>
    use Text::Embed qr(&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;(\w*?)&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;);</pre>
</dd>
<dd>
<p>A regular expression will be used in a call to <code>split()</code>. Any 
leading or trailing empty strings will be removed automatically.</p>
</dd>
<dt><strong><a name="item_code">CODE</a></strong><br />
</dt>
<dd>
<pre>
    use Text::Embed sub{$_ = shift; ...}
    use Text::Embed &amp;Some::Other::Function;</pre>
</dd>
<dd>
<p>A subroutine will be passed a reference to the __DATA__ <em>string</em>. 
It should return a LIST of key-value pairs.</p>
</dd>
</dl>
<p>In the name of laziness, <strong>Text::Embed</strong> provides a couple of 
predefined formats:</p>
<dl>
<dt><strong><a name="item__3adefault">:default</a></strong><br />
</dt>
<dd>
Line-oriented __DATA__ like format:
</dd>
<dd>
<pre>
    __BAZ__ 
    baz baz baz
    __FOO__
    foo foo foo
    foo foo foo</pre>
</dd>
<p></p>
<dt><strong><a name="item__3adefine">:define</a></strong><br />
</dt>
<dd>
CPP-like format (%DATA is readonly - can be used to define constants):
</dd>
<dd>
<pre>
    #define BAZ     baz baz baz
    #define FOO     foo foo foo
                    foo foo foo</pre>
</dd>
<p></p>
<dt><strong><a name="item__3acdata">:cdata</a></strong><br />
</dt>
<dd>
Line-agnostic CDATA-like format. Anything outside of tags is ignored.
</dd>
<dd>
<pre>
    &lt;![BAZ[baz baz baz]]&gt;
    &lt;![FOO[
        foo foo foo
        foo foo foo
    ]]&gt;</pre>
</dd>
<p></p></dl>
<p>
</p>
<h3><a name="stage_2__processing">Stage 2: Processing</a></h3>
<p>After parsing, each key-value pair can be further processed by an arbitrary
number of callbacks.</p>
<p>A common usage of this might be controlling how whitespace is represented 
in each segment. <strong>Text::Embed</strong> provides some likely defaults which operate
on the hash values only.</p>
<dl>
<dt><strong><a name="item__3atrim">:trim</a></strong><br />
</dt>
<dd>
Removes trailing or leading whitespace
</dd>
<p></p>
<dt><strong><a name="item__3acompress">:compress</a></strong><br />
</dt>
<dd>
Substitutes zero or more whitspace with a single &lt;SPACE&gt;
</dd>
<p></p>
<dt><strong><a name="item__3ablock_2dindent">:block-indent</a></strong><br />
</dt>
<dd>
Removes trailing or leading blank lines, preserves all indentation
</dd>
<p></p>
<dt><strong><a name="item__3ablock_2dnoindent">:block-noindent</a></strong><br />
</dt>
<dd>
Removes trailing or leading blank lines, preserves unique indentation
</dd>
<p></p>
<dt><strong><a name="item__3araw">:raw</a></strong><br />
</dt>
<dd>
Leave untouched
</dd>
<p></p>
<dt><strong>:default</strong><br />
</dt>
<dd>
Same as <strong>:raw</strong>
</dd>
<p></p></dl>
<p>If you need more control, CODE references or named subroutines can be 
invoked as necessary. At this point it is safe to rename or modify keys.