view release on metacpan or  search on metacpan

doc/html/guide.html  view on Meta::CPAN

		</p><pre class="programlisting">{a\{} b\}c</pre><p>
		Any other Perl backslash escapes, such as <span class="quote">&#8220;<span class="quote">\n</span>&#8221;</span> 
		or <span class="quote">&#8220;<span class="quote">\x20</span>&#8221;</span>, work too. The quote characters have no
		special meaning, they don't need to be escaped and they don't group
		the words. For example, the following two are equivalent:
		</p><pre class="programlisting">"a b c"
{"a} {b} {c"}</pre><p>
		Escaping the spaces (<span class="quote">&#8220;<span class="quote">\ </span>&#8221;</span>) provides another way
		to combine the words into one element. The following two
		are equivalent:
		</p><pre class="programlisting">{a b c}
a\ b\ c</pre><p>
		There is no need for the nested escaping.  The characters need
		to be escaped only once, and then the resulting strings can be
		wrapped into any number of brace levels.
		</p><p>
		All the methods in this module are static, there are no objects.
		</p><pre class="programlisting">$string = $data;
@elements = Triceps::Braced::raw_split_braced($string)
confess "Unbalanced braces around '$string'" if $string;</pre><p>
		Split the string into the braced elements. If any of the elements
		were enclosed into their own braces, these braces are left in place,
		the element string will still contain them. For example, <span class="quote">&#8220;<span class="quote">a {b} {c d}</span>&#8221;</span>
		will be split into <span class="quote">&#8220;<span class="quote">a</span>&#8221;</span>, <span class="quote">&#8220;<span class="quote">{b}</span>&#8221;</span>, <span class="quote">&#8220;<span class="quote">{c d}</span>&#8221;</span>.
		No unescaping is done, the escaped characters are passed through as-is.
		This method of splitting is rarely used, it's present as a baseline.
		</p><p>
		The original string argument will be fully consumed. If anything is left
		unconsumed, this is an indication of a syntax error, with unbalanced
		braces. The argument may not be a constant because it gets modified.
		</p><pre class="programlisting">$string = $data;
@elements = Triceps::Braced::split_braced($string)
confess "Unbalanced braces around '$string'" if $string;</pre><p>
		Split the string into the braced elements. If any of the elements
		were enclosed into their own braces, these braces will be removed from the
		results.  For example, <span class="quote">&#8220;<span class="quote">a {b} {c d}</span>&#8221;</span>
		will be split into <span class="quote">&#8220;<span class="quote">a</span>&#8221;</span>, <span class="quote">&#8220;<span class="quote">b</span>&#8221;</span>, <span class="quote">&#8220;<span class="quote">c d</span>&#8221;</span>.
		No unescaping is done, the escaped characters are passed through as-is.
		This is the normal method of splitting, it allows the elements
		to be split further recursively.
		</p><p>
		The original string argument will be fully consumed. If anything is left
		unconsumed, this is an indication of a syntax error, with unbalanced
		braces. The argument may not be a constant because it gets modified.
		</p><pre class="programlisting">$result = Triceps::Braced::bunescape($string);</pre><p>
		Un-escape a string by processing all the escape characters in it.
		This step is normally done last, after all the splitting is done.
		The result will become unsuitable for the future splitting because
		the escaped characters will lose their special meaning. If any
		literal braces are present in the argument, they will pass through
		to the result as literals. For example, <span class="quote">&#8220;<span class="quote">{a \{b }</span>&#8221;</span>
		will become <span class="quote">&#8220;<span class="quote">{a {b }</span>&#8221;</span>.
		</p><pre class="programlisting">@results = Triceps::Braced::bunescape_all(@strings);</pre><p>
		Perform the un-escaping on a whole array of strings. The result
		array will contain the same number of elements as the argument.
		</p><pre class="programlisting">$ref_results = Triceps::Braced::split_braced_final($string);
confess "Unbalanced braces around '$string'" if $string;</pre><p>
		The combined functionality of splitting a string and un-escaping
		the result elements. That's why it's final: no further splits must be
		done after un-escaping.  <span class="bold"><strong>The return value is different from the
		other split methods.</strong></span> It is a reference to the array of result
		strings. The difference has been introduced to propagate the <code class="computeroutput">undef</code>
		from the argument to the result: if the argument string is <code class="computeroutput">undef</code>,
		the result will be also <code class="computeroutput">undef</code>, <span class="bold"><strong>not</strong></span> a reference to an
		empty array. The string gets consumed in the same way as for the
		other split methods, and anything left in it indicates an unbalanced
		brace.
		</p></div><div class="sect1" title="19.17. FnReturn reference"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sc_ref_fnreturn"></a>19.17. FnReturn reference</h2></div></div></div><a class="indexterm" name="idm9104">...
		The FnReturn represents the return value of a streaming function.
		The return value consists of a stream of rowops, and gets processed
		by sending them to the labels through a binding.
		</p><pre class="programlisting">$fret = Triceps::FnReturn-&gt;new($optName =&gt; $optValue, ...);</pre><p>
		Construct an FnReturn object. The options are:
		</p><div class="variablelist"><dl><dt><span class="term"><code class="computeroutput">name =&gt; $name</code></span></dt><dd>
			Name of this object. Will be used to create the names of the labels in it.
			</dd><dt><span class="term"><code class="computeroutput">unit =&gt; $unit</code></span></dt><dd>
			The unit where this object belongs.
			</dd><dt><span class="term"><code class="computeroutput">labels =&gt; [ @definitions ]</code></span></dt><dd><p>
			Definition of the labels in the FnReturn, where the results of the
			streaming function will be sent.
			The full names of these labels will be
			<span class="quote">&#8220;<span class="quote">return_name.label_name</span>&#8221;</span>. The label names within a 
			return must be unique.
			The value for this option is an array
			reference, with the labels defined as name-value pairs in the array, in
			one of two forms:
			</p><pre class="programlisting">labels =&gt; [
  $name1 =&gt; $rowType1,
  $name2 =&gt; $fromLabel2,
  ...
]</pre><p>
			If the second element in the pair is a row type, a label of that row type
			will be created in the FnReturn.
			</p><p>
			If the second element in the pair is a label, its row type will be used
			to create a label in FnReturn and that new label will also be automatically
			chained off the specified one. This is convenient if you already have
			the logic of the function defined and just want to forward the result
			data from an existing label into the FnReturn. The chaining is normally
			done with <code class="computeroutput">chainFront()</code>, unless the option <code class="computeroutput">chainFront =&gt; 0</code>
			tells otherwise. 
			The front chaining is convenient if you want to pass both
			the original request and the result into the return. Usually you
			would define the result computation and then define the return.
			With the chaining at the back, this would lead to the computation
			chained off the input label first and the return going after it.
			This would lead to the result coming out before the argument,
			and special contortions would be needed to avoid it. With chaining
			at the front, the return will go in the chain before the computation,
			even if the return was defined last.
			</p></dd><dt><span class="term"><code class="computeroutput">chainFront =&gt; 0/1</code></span></dt><dd>
			Flag: Determines whether the FnReturn labels built by chaining off the other
			labels will be chained at the back (if 0) or at the front (if 1).
			Optional. Default: 1.
			</dd><dt><span class="term"><code class="computeroutput">onPush =&gt; $code</code></span></dt><dd>
			The code to execute whenever an FnBinding is pushed onto this FnReturn.
			This is useful to maintain the extended call contexts for the streaming
			function.
			Its argument can be specified in one of two forms: either just a code
			reference, or a reference to an array containing the code reference and
			the extra arguments for it. I.e. either <code class="computeroutput">onPush =&gt; $code</code> or
			<code class="computeroutput">onPush =&gt; [ $code, @args ]</code>. The first argument of the function
			will always be the FnReturn object itself, with extra arguments going
			after it: <code class="computeroutput">&amp;$code($thisFnReturn, @optional_args)</code>.
			As usual, a source code string may be used instead of the function reference.
			Optional.