Fossil

Check-in [905f67d0]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Added th1_ob.wiki embedded doc.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | th1-query-api
Files: files | file ages | folders
SHA1: 905f67d0d36fe13350ae0914754c8de3bca04a9d
User & Date: stephan 2012-07-14 20:11:52
Context
2012-07-14
20:45
Refactored th1 query API to use (query foo) instead of query_foo. Added th1_query.wiki doc page. check-in: bd98f0f4 user: stephan tags: th1-query-api
20:11
Added th1_ob.wiki embedded doc. check-in: 905f67d0 user: stephan tags: th1-query-api
19:48
Fixed a segfault in proc_command() caused by invalid inspection of an empty array. check-in: f2d87242 user: stephan tags: th1-query-api
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Added www/th1_ob.wiki.











































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
<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,
and provides these features:

   *  Redirect output from <tt>puts</tt> and friends to a buffer.
   *  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.

Example usage:

<nowiki><pre>
&lt;th1>
puts "this is unbuffered"
ob start
# all output until the next ob start|end gets collected
# in a buffer...
&lt;/th1>

this is buffered

&lt;th1>
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 end]
# That is equivalent to:
#  set buf [ob get]
#  ob  end

puts "\nThis is now unbuffered, but we buffered: $buf\n"
&lt;/th1>
</pre></nowiki>

The functions are summarized below...

<h2>ob start</h2>

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

<h2>ob end</h2>

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.

The global resources associated with buffering are cleaned up when the
last buffering level is left (and re-created as needed when a new
level is started).

<h2>ob clean</h2>

This discards the current contents of the current buffer level but
does not change the buffer stack level.

<h2>ob get</h2>

This fetches the current contents as a string. It optionally accepts
either <tt>end</tt> or <tt>clean</tt>, in which cases it behaves like
either <tt>ob end</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</tt> pops the buffer off the
stack after fetching its contents.

<h2>ob level</h2>

Returns the current buffering level (0 if not buffering).

<h2>ob flush</h2>

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.