<h1>TH1 "ob" (Output Buffering) API</h1>
The "ob" API mimics the
[http://php.net/manual/en/function.ob-start.php|PHP output buffering] fairly closely, providing these features:
* Redirect output from <tt>puts</tt> and friends to a buffer. Any output which goes through the C-level <tt>Th1_Output()</tt> function gets captured this way.
* Fetch the buffer as a string or discard it (as you wish).
* Supports nesting buffering arbitrarily deep, but each level which gets opened must also be closed by the scripter.
To add it to an interpreter, the library must have been built with <tt>TH1_ENABLE_OB</tt> defined (to any value) and the client must call <tt>th1_register_ob()</tt>, passing it his interpreter instance. Note that <tt>th1_register_ob()</tt> is only declared and defined if <tt>TH1_ENABLE_OB</tt> is defined (which it is, by default, in <tt>th1.h</th>).
(note the <tt><TH1></tt> tags - this input is intended for <tt>Th1_Render()</tt>, not <tt>Th1_Eval()</tt>. The former filters "text documents" with embedded TH1 and the latter runs "plain" script code.)
puts "this is unbuffered"
ob push # or: ob start (same thing)
# all output until the next ob start|end gets collected
# in a buffer...
this is buffered
puts "current buffer level = " [ob level] "\n"
puts "this part is also collected in the buffer."
# Collect the buffer's contents:
set buf [ob get pop]
# That is equivalent to:
# set buf [ob get]
# ob pop
puts "\nThis is not buffered, but we buffered: $buf\n"
The functions are summarized below...
<tt>push</tt> and <tt>start</tt> are aliases ("start" comes from the PHP API, but
"push" is probably more natural to those working with th1).
<tt>ob start</tt> pushes a level of buffering onto the buffer stack, such that
future calls which generate output through the th1-internal mechanism will have it
transparently redirected to the current buffer.
It is important that every call to <tt>ob start</tt> be followed up (eventually)
by either <tt>ob end</tt> or <tt>ob get end</tt>.
<tt>pop</tt> and <tt>end</tt> are aliases ("end" comes from the PHP API, but
"pop" is probably more natural to those working with th1).
This discards any current buffered contents and reverts the output state to
the one it had before the previous <tt>ob start</tt>. i.e. that might be another
buffering level or it might be the th1-normal output mechanism.
This discards the current contents of the current buffer level but
does not change the buffer stack level.
This fetches the current contents as a string. It optionally accepts
either <tt>end</tt> (or its alias <tt>pop</tt>) or <tt>clean</tt>, in which cases it behaves like either <tt>ob end|pop</tt> or <tt>ob clean</tt>, respectively, in addition to returning the buffer contents. i.e. <tt>ob get clean</tt> will fetch the contents and clean up the buffer, but does not change the buffering level, whereas <tt>ob get end|pop</tt> pops the buffer off the stack after fetching its contents.
Returns the current buffering level (0 if not buffering).
It is not expected that this will be useful all that often, but for
the cases where it is, here's how it works: this behaves as if we
fetched the buffer state (<tt>ob get</tt>), reverted TH1 to its
previous output mechanism, push the buffer state to TH1, revert TH1
<em>back</em> to the current buffering state, and then clear the
current buffer contents (like <tt>ob clean</tt>). This does not change
the buffering level, though it temporarily behaves as if it does.
In other words, this function pushes the current buffer contents to the
next-lower output mechanism (which may be another ob buffering level, it might be be <tt>fwrite(stdout)</tt>, or whatever output mechanism the library user installed for the interpreter).