view release on metacpan or  search on metacpan

doc/src/docsrc/760braced.xml  view on Meta::CPAN

		<para>
		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.
		</para>

<pre>
$string = $data;
@elements = Triceps::Braced::split_braced($string)
confess "Unbalanced braces around '$string'" if $string;
</pre>

		<para>
		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, <quote>a {b} {c d}</quote>
		will be split into <quote>a</quote>, <quote>b</quote>, <quote>c d</quote>.
		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.
		</para>

		<para>
		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.
		</para>

<pre>
$result = Triceps::Braced::bunescape($string);
</pre>

		<para>
		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, <quote>{a \{b }</quote>
		will become <quote>{a {b }</quote>.
		</para>

<pre>
@results = Triceps::Braced::bunescape_all(@strings);
</pre>

		<para>
		Perform the un-escaping on a whole array of strings. The result
		array will contain the same number of elements as the argument.
		</para>

<pre>
$ref_results = Triceps::Braced::split_braced_final($string);
confess "Unbalanced braces around '$string'" if $string;
</pre>

		<para>
		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.  <b>The return value is different from the
		other split methods.</b> It is a reference to the array of result
		strings. The difference has been introduced to propagate the <pre>undef</pre>
		from the argument to the result: if the argument string is <pre>undef</pre>,
		the result will be also <pre>undef</pre>, <b>not</b> 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.
		</para>

	</sect1>