1.22Out of band items support

Handle out of band items.

Out-of-band items are normal items which can be tested for the out-of-band quality through the isoob 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 map function drops the item (acting like filter ), if it is out-of-band.

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.

   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 )

Marking an item as out-of-band allows the creation of monads 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.

Functions

deoob

Turns an out-of-band item in a normal item.

deoob( item )

item	The out of band item to be turned into a normal item.
Return	An the non-out-of-band version version of the item.

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 oob for a deeper explanation of OOB items.

isoob

Checks for the out-of-band status of an item.

isoob( item )

item	The item to be checked.
Return	True if the item is out of band, false otherwise.

This function can be used to check if a certain item is an out of band item.

oob

Generates an out-of-band item.

oob( [item] )

item	The item to be declared out of band.
Return	An oob version of the item, or an oob nil if no item is given.

This function returns an out-of-band nil item, or if a parameter is given, an out-of-band version of that item.