<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Function set "Out of band items support" - Function set "Out of band items support"</title>
<link href="faldoc.css" rel="stylesheet" type="text/css"/>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
</head>
<body class="faldoc_body">
<div class="navitop">
<div class="tabs">
<ul>
<li><a href="./index.html"><span>Main</span></a></li>
<li><a href="./pages.html"><span>Related pages</span></a></li>
<li><a href="./groups.html"><span>Groups</span></a></li>
<li><a href="./funset.html"><span>Function sets</span></a></li>
<li><a href="./classes.html"><span>Classes</span></a></li>
<li><a href="./objects.html"><span>Objects</span></a></li>
<li><a href="./functions.html"><span>All functions</span></a></li>
<li><a href="./globals.html"><span>Globals</span></a></li>
</ul>
</div>
</div>
<hr/>
<h1 class="faldoc_title">Function set "Out of band items support"</h1>
<p class="faldoc_brief">Handle out of band items. </p>
<p class="faldoc_brief"><a href="#more">more...</a></p>
<h2 class="faldoc_title">Summary</h2>
<table class="faldoc_list">
<tr><td><a href="#deoob">deoob()</a></td><td>Turns an out-of-band item in a normal item. </td></tr>
<tr><td><a href="#isoob">isoob()</a></td><td>Checks for the out-of-band status of an item. </td></tr>
<tr><td><a href="#oob">oob()</a></td><td>Generates an out-of-band item. </td></tr>
</table>
<a name="more"><h2 class="faldoc_title">Detailed description</h2></a>
<table class="faldoc_function">
</table>
<br/>
<p class="item_brief">Handle out of band items. </p>
<p class="faldoc_text"> Out-of-band items are normal items which can be tested for the out-of-band quality through the <a href="./functions.html#isoob">isoob</a> function to perform special tasks. Some core and RTL functions can check for the item being out-of-band to take special decisions about the item, or to modify their behavior. For example, the <a href="./functions.html#map">map</a> function drops the item (acting like <a href="./functions.html#filter">filter</a>), if it is out-of-band. </p>
<p class="faldoc_text">This feature is available also to scripts; functions accepting any kind of items from callbacks they are using to generate data may wish to receive special instructions through out of band data. In the next example, a data producer returns a set of items one at a time, and notifies the caller to switch to another producer via an out-of-band notification. </p>
<pre class="faldoc_code">
function firstSeries()
static: vals = [1, 2, 3, 4 ]
if vals: return arrayHead( vals )
// notify the next function
return oob( secondSeries )
end
function secondSeries()
static: vals = [ "a", nil, "b", 4 ]
if vals: return arrayHead( vals )
// notify we're done with an nil OOB
return oob()
end
function consumer( producer )
loop item = producer()
if isoob( item )
// An OOB means we have something special. If it's nil, we're done...
if item == nil: return
// else it's the notification of a new producer
producer = item
else
// if it's not an OOB, then we must process it
> "Received item: ", item
end
end
end
consumer( firstSeries )
</pre>
<p class="faldoc_text"> Marking an item as out-of-band allows the creation of <i>monads</i> in functional evaluations. More automatism will be introduced in future, but scripters can have monads by assigning the oob status to complex objects and perform out-of-band processing on them. </p>
<h2 class="faldoc_title">Members</h2>
<h3 class="faldoc_funcname"><a name="deoob">deoob()</a></h3>
<p class="item_brief">Turns an out-of-band item in a normal item. </p>
<p class="faldoc_funcdecl">deoob( item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The out of band item to be turned into a normal item. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An the non-out-of-band version version of the item. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> The function returns a flat copy of the item without the out-of-band status set. If the item was initially not OOB, then deoob() does nothing. See <a href="./functions.html#oob">oob</a> for a deeper explanation of OOB items. </p>
</p>
<h3 class="faldoc_funcname"><a name="isoob">isoob()</a></h3>
<p class="item_brief">Checks for the out-of-band status of an item. </p>
<p class="faldoc_funcdecl">isoob( item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item to be checked. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if the item is out of band, false otherwise. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function can be used to check if a certain item is an out of band item. </p>
</p>
<h3 class="faldoc_funcname"><a name="oob">oob()</a></h3>
<p class="item_brief">Generates an out-of-band item. </p>
<p class="faldoc_funcdecl">oob( [item] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_optparam">item</td><td class="faldoc_optparamdesc">The item to be declared out of band. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> An oob version of the item, or an oob <b>nil</b> if no item is given. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function returns an out-of-band nil item, or if a parameter is given, an out-of-band version of that item. </p>
</p>
<hr/>
<div class="navibottom">
<center>
<a href="./index.html">Main</a> - <a href="./pages.html">Related pages</a> - <a href="./groups.html">Groups</a> - <a href="./funset.html">Function sets</a> - <a href="./classes.html">Classes</a> - <a href="./objects.html">Objects</a> - <a href="./functions.html">All functions</a> - <a href="./globals.html">Globals</a>
</center>
</div>
</div>
<div class="faldoc_signature">Made with <a href="http://www.falconpl.org">faldoc 2.2.0</div>
</body>
</html>
