|
1
|
<h1>TH1 "ob" (Output Buffering) API</h1> |
|
2
|
|
|
3
|
The "ob" API mimics the |
|
4
|
[http://php.net/manual/en/function.ob-start.php|PHP output buffering] fairly closely, |
|
5
|
and provides these features: |
|
6
|
|
|
7
|
* Redirect output from <tt>puts</tt> and friends to a buffer. |
|
8
|
* Fetch the buffer as a string or discard it (as you wish). |
|
9
|
* Supports nesting buffering arbitrarily deep, but each level which gets opened must also be closed by the scripter. |
|
10
|
|
|
11
|
Example usage: |
|
12
|
|
|
13
|
<nowiki><pre> |
|
14
|
<th1> |
|
15
|
puts "this is unbuffered" |
|
16
|
ob push # or: ob start (same thing) |
|
17
|
# all output until the next ob start|end gets collected |
|
18
|
# in a buffer... |
|
19
|
</th1> |
|
20
|
|
|
21
|
this is buffered |
|
22
|
|
|
23
|
<th1> |
|
24
|
puts "current buffer level = " [ob level] "\n" |
|
25
|
puts "this part is also collected in the buffer." |
|
26
|
|
|
27
|
# Collect the buffer's contents: |
|
28
|
set buf [ob get pop] |
|
29
|
# That is equivalent to: |
|
30
|
# set buf [ob get] |
|
31
|
# ob pop |
|
32
|
|
|
33
|
puts "\nThis is now unbuffered, but we buffered: $buf\n" |
|
34
|
</th1> |
|
35
|
</pre></nowiki> |
|
36
|
|
|
37
|
The functions are summarized below... |
|
38
|
|
|
39
|
<h2>ob push|start</h2> |
|
40
|
|
|
41
|
<tt>push</tt> and <tt>start</tt> are aliases ("start" comes from the PHP API, but |
|
42
|
"push" is probably more natural to those working with th1). |
|
43
|
|
|
44
|
<tt>ob start</tt> pushes a level of buffering onto the buffer stack, such that |
|
45
|
future calls which generate output through the th1-internal mechanism will have it |
|
46
|
transparently redirected to the current buffer. |
|
47
|
|
|
48
|
It is important that every call to <tt>ob start</tt> be followed up (eventually) |
|
49
|
by either <tt>ob end</tt> or <tt>ob get end</tt>. |
|
50
|
|
|
51
|
<h2>ob pop|end</h2> |
|
52
|
|
|
53
|
<tt>pop</tt> and <tt>end</tt> are aliases ("end" comes from the PHP API, but |
|
54
|
"pop" is probably more natural to those working with th1). |
|
55
|
|
|
56
|
This discards any current buffered contents and reverts the output state to |
|
57
|
the one it had before the previous <tt>ob start</tt>. i.e. that might be another |
|
58
|
buffering level or it might be the th1-normal output mechanism. |
|
59
|
|
|
60
|
The global resources associated with buffering are cleaned up when the |
|
61
|
last buffering level is left (and re-created as needed when a new |
|
62
|
level is started). |
|
63
|
|
|
64
|
<h2>ob clean</h2> |
|
65
|
|
|
66
|
This discards the current contents of the current buffer level but |
|
67
|
does not change the buffer stack level. |
|
68
|
|
|
69
|
<h2>ob get</h2> |
|
70
|
|
|
71
|
This fetches the current contents as a string. It optionally accepts |
|
72
|
either <tt>end</tt> (or its alias <tt>pop</tt>) or <tt>clean</tt>, in which cases it behaves like |
|
73
|
either <tt>ob end|pop</tt> or <tt>ob clean</tt>, respectively, in addition |
|
74
|
to returning the buffer contents. i.e. <tt>ob get clean</tt> will |
|
75
|
fetch the contents and clean up the buffer, but does not change the |
|
76
|
buffering level, whereas <tt>ob get end|pop</tt> pops the buffer off the |
|
77
|
stack after fetching its contents. |
|
78
|
|
|
79
|
<h2>ob level</h2> |
|
80
|
|
|
81
|
Returns the current buffering level (0 if not buffering). |
|
82
|
|
|
83
|
<h2>ob flush</h2> |
|
84
|
|
|
85
|
It is not expected that this will be useful all that often, but for |
|
86
|
the cases where it is, here's how it works: this behaves as if we |
|
87
|
fetched the buffer state (<tt>ob get</tt>), reverted TH1 to its |
|
88
|
previous output mechanism, push the buffer state to TH1, revert TH1 |
|
89
|
<em>back</em> to the current buffering state, and then clear the |
|
90
|
current buffer contents (like <tt>ob clean</tt>). This does not change |
|
91
|
the buffering level, though it temporarily behaves as if it does. |
|
92
|
|
|
93
|
In other words, this function pushes the current buffer contents to the |
|
94
|
next-lower output mechanism (which may be another ob buffering level, |
|
95
|
fossil's internal CGI output buffer, or it might be be |
|
96
|
<tt>fwrite(stdout)</tt>). |