1 |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> |
2 |
<html xmlns="http://www.w3.org/1999/xhtml"> |
3 |
<head> |
4 |
<title>Whatpm::CacheManifest - An HTML5 Cache Manifest Parser</title> |
5 |
<link rel="stylesheet" href="http://suika.fam.cx/www/style/html/pod.css" type="text/css" /> |
6 |
<link rev="made" href="mailto:admin@suika.fam.cx" /> |
7 |
</head> |
8 |
|
9 |
<body> |
10 |
|
11 |
<p><a name="__index__"></a></p> |
12 |
<!-- INDEX BEGIN --> |
13 |
|
14 |
<ul> |
15 |
|
16 |
<li><a href="#name">NAME</a></li> |
17 |
<li><a href="#synopsis">SYNOPSIS</a></li> |
18 |
<li><a href="#description">DESCRIPTION</a></li> |
19 |
<li><a href="#methods">METHODS</a></li> |
20 |
<li><a href="#manifest_data_structure">MANIFEST DATA STRUCTURE</a></li> |
21 |
<li><a href="#dependency">DEPENDENCY</a></li> |
22 |
<li><a href="#see_also">SEE ALSO</a></li> |
23 |
<li><a href="#todo">TODO</a></li> |
24 |
<li><a href="#author">AUTHOR</a></li> |
25 |
<li><a href="#license">LICENSE</a></li> |
26 |
</ul> |
27 |
<!-- INDEX END --> |
28 |
|
29 |
<hr /> |
30 |
<p> |
31 |
</p> |
32 |
<h1><a name="name">NAME</a></h1> |
33 |
<p>Whatpm::CacheManifest - An HTML5 Cache Manifest Parser</p> |
34 |
<p> |
35 |
</p> |
36 |
<hr /> |
37 |
<h1><a name="synopsis">SYNOPSIS</a></h1> |
38 |
<pre> |
39 |
use Whatpm::CacheManifest; |
40 |
|
41 |
my $manifest_uri = q<<a href="http://www.example.com/manifest>">http://www.example.com/manifest></a>;; |
42 |
my ($manifest_data, $manifest_base_uri) |
43 |
= some_function_to_retrieve_content ($manifest_uri); |
44 |
|
45 |
# or, |
46 |
|
47 |
my $manifest = Whatpm::CacheManifest->parse_byte_string |
48 |
($manifest_data, $manifest_uri, $manifest_base_uri, sub { |
49 |
my %err = @_; |
50 |
warn $err{type}, "\n"; |
51 |
}); |
52 |
|
53 |
$manifest_data = Encode::decode ('utf-8', $manifest_data); |
54 |
my $manifest = Whatpm::CacheManifest->parse_char_string |
55 |
($manifest_data, $manifest_uri, $manifest_base_uri, sub { |
56 |
my %err = @_; |
57 |
warn $err{type}, "\n"; |
58 |
}); |
59 |
|
60 |
# $manifest->[0]: Array reference of explicit URIs. |
61 |
# $manifest->[1]: Hash reference of fallback URIs. |
62 |
# $manifest->[2]: Array reference of online whitelist.</pre> |
63 |
<p> |
64 |
</p> |
65 |
<hr /> |
66 |
<h1><a name="description">DESCRIPTION</a></h1> |
67 |
<p>The <code>Whatpm::CacheManifest</code> module implements the parsing algorithm |
68 |
for HTML5 cache manifest format, used to describe an offline Web |
69 |
application.</p> |
70 |
<p> |
71 |
</p> |
72 |
<hr /> |
73 |
<h1><a name="methods">METHODS</a></h1> |
74 |
<p>This module provides two class methods to parse cache manifests:</p> |
75 |
<dl> |
76 |
<dt><strong><a name="item_parse_byte_string"><em>$manifest</em> = Whatpm::CacheManifest->parse_byte_string (<em>$manifest_bytes</em>, <em>$manifest_uri</em>, <em>$manifest_base_uri</em>, <em>$onerror</em>)</a></strong><br /> |
77 |
</dt> |
78 |
<dt><strong><a name="item_parse_char_string"><em>$manifest</em> = Whatpm::CacheManifest->parse_char_string (<em>$manifest_chars</em>, <em>$manifest_uri</em>, <em>$manifest_base_uri</em>, <em>$onerror</em>)</a></strong><br /> |
79 |
</dt> |
80 |
</dl> |
81 |
<p>These methods parse a cache manifest and return that cache manifest |
82 |
in the <a href="#manifest_data_structure">MANIFEST DATA STRUCTURE</a>.</p> |
83 |
<p>Parameters:</p> |
84 |
<dl> |
85 |
<dt><strong><a name="item__24manifest_bytes"><em>$manifest_bytes</em></a></strong><br /> |
86 |
</dt> |
87 |
<dd> |
88 |
The content of the manifest files, as a Perl byte string. |
89 |
It may or may not be a valid cache manifest. It will be processed |
90 |
as defined by HTML5 cache manifest parsing specification. |
91 |
It will be interpreted as UTF-8 string, as defined in the specification. |
92 |
</dd> |
93 |
<p></p> |
94 |
<dt><strong><a name="item__24manfiest_chars"><em>$manfiest_chars</em></a></strong><br /> |
95 |
</dt> |
96 |
<dd> |
97 |
The content of the manifest files, as a Perl character string. |
98 |
It may or may not be a valid cache manifest. It will be processed |
99 |
as defined by HTML5 cache manifest parsing specification. It may |
100 |
contain <code>U+0000</code> <code>NULL</code> characters; they are converted to |
101 |
<code>U+FFFD</code> <code>REPLACEMENT CHARACTER</code>s as defined in the specification. |
102 |
</dd> |
103 |
<p></p> |
104 |
<dt><strong><a name="item__24manifest_uri"><em>$manifest_uri</em></a></strong><br /> |
105 |
</dt> |
106 |
<dd> |
107 |
The IRI of the cache manifest. |
108 |
</dd> |
109 |
<p></p> |
110 |
<dt><strong><a name="item__24manifest_base_uri"><em>$manifest_base_uri</em></a></strong><br /> |
111 |
</dt> |
112 |
<dd> |
113 |
The base IRI of the cache manifest. |
114 |
</dd> |
115 |
<p></p> |
116 |
<dt><strong><a name="item__24onerror"><em>$onerror</em></a></strong><br /> |
117 |
</dt> |
118 |
<dd> |
119 |
The callback function that will be invoked if the manifest cache |
120 |
has an error (or a warning). It may be omitted. If omitted, |
121 |
any error (or warning) is <code>warn</code>ed with its <code>type</code>. |
122 |
</dd> |
123 |
<dd> |
124 |
<p>@@ TBW</p> |
125 |
</dd> |
126 |
<dd> |
127 |
<p>For the list of the error types, see Whatpm Error Types |
128 |
<http://suika.fam.cx/gate/2005/sw/Whatpm%20Error%20Types>.</p> |
129 |
</dd> |
130 |
<p></p></dl> |
131 |
<p>In addition, a class method to check conformance of cache manifests |
132 |
is provided:</p> |
133 |
<dl> |
134 |
<dt><strong><a name="item_check_manifest">Whatpm::CacheManifest->check_manifest (<em>$manifest</em>, <em>$onerror</em>)</a></strong><br /> |
135 |
</dt> |
136 |
<dd> |
137 |
Check conformance of a cache manifest, given as <em>$manifest</em>. |
138 |
</dd> |
139 |
<dl> |
140 |
<dt><strong><a name="item__24manifest"><em>$manifest</em></a></strong><br /> |
141 |
</dt> |
142 |
<dd> |
143 |
The cache manifest to check, encoded in the <a href="#manifest_data_structure">MANIFEST DATA STRUCTURE</a>. |
144 |
</dd> |
145 |
<p></p> |
146 |
<dt><strong><em>$onerror</em></strong><br /> |
147 |
</dt> |
148 |
<dd> |
149 |
The callback function that will be invoked if the manifest cache |
150 |
has an error (or a warning). It may be omitted. If omitted, |
151 |
any error (or warning) is <code>warn</code>ed with its <code>type</code>. |
152 |
</dd> |
153 |
<dd> |
154 |
<p>@@ TBW</p> |
155 |
</dd> |
156 |
<dd> |
157 |
<p>For the list of the error types, see Whatpm Error Types |
158 |
<http://suika.fam.cx/gate/2005/sw/Whatpm%20Error%20Types>.</p> |
159 |
</dd> |
160 |
<dd> |
161 |
<p><code>index</code> is the index of the IRI with the error. @@ TBW</p> |
162 |
</dd> |
163 |
<p></p></dl> |
164 |
<p>A cache manifest is conforming if (a) it is correctly labeled |
165 |
as a cache manifest (e.g. as Internet media type <code>text/cache-manifest</code>) |
166 |
in the transfer layer, (b) parsing the cache manifest by |
167 |
<a href="#item_parse_byte_string"><code>parse_byte_string</code></a> or <a href="#item_parse_char_string"><code>parse_char_string</code></a> raises no error |
168 |
with level <code>m</code> or <code>s</code>, and (c) checking the cache manifest by |
169 |
<a href="#item_check_manifest"><code>check_manifest</code></a> raises no error with level <code>m</code> or <code>s</code>.</p> |
170 |
</dl> |
171 |
<p> |
172 |
</p> |
173 |
<hr /> |
174 |
<h1><a name="manifest_data_structure">MANIFEST DATA STRUCTURE</a></h1> |
175 |
<p>If <em>$m</em> is in manifest data structure, <em>$m</em> is a reference to |
176 |
the array with three items: <em>$explicit_uris</em>, <em>$fallback_uris</em>, |
177 |
<em>$online_whitelist</em>, and <em>$manifest_uri</em>.</p> |
178 |
<p><em>$explicit_uris</em> is a reference to the array, which |
179 |
contains zero or more strings. The strings are IRI references |
180 |
of the explicit entries.</p> |
181 |
<p><em>$fallback_uris</em> is a reference to the hash, which |
182 |
contains zero or more mappings of strings (keys) to strings (values). |
183 |
The keys are IRI references of the oppotunistic caching namespaces. |
184 |
The values are IRI references of the fallback entries corresponding |
185 |
to the oppotunistic caching namespaces.</p> |
186 |
<p><em>$online_whitelist</em> is a reference to the array, which |
187 |
contains zero or more strings. The strings are IRI references |
188 |
in the online whitelist.</p> |
189 |
<p><em>$manfest_uri</em> is a string which is an IRI reference of the |
190 |
manifest itself.</p> |
191 |
<p> |
192 |
</p> |
193 |
<hr /> |
194 |
<h1><a name="dependency">DEPENDENCY</a></h1> |
195 |
<p>This module depends on <a href="../Message/URI/URIReference.html">the Message::URI::URIReference manpage</a>, which is |
196 |
part of the manakai-core package.</p> |
197 |
<p> |
198 |
</p> |
199 |
<hr /> |
200 |
<h1><a name="see_also">SEE ALSO</a></h1> |
201 |
<p>Whatpm Error Types |
202 |
<http://suika.fam.cx/gate/2005/sw/Whatpm%20Error%20Types>.</p> |
203 |
<p>HTML5 |
204 |
<http://whatwg.org/html5>.</p> |
205 |
<p><a href="../Message/URI/URIReference.html">the Message::URI::URIReference manpage</a> |
206 |
<http://suika.fam.cx/www/manakai-core/lib/Message/URI/URIReference.html>.</p> |
207 |
<p> |
208 |
</p> |
209 |
<hr /> |
210 |
<h1><a name="todo">TODO</a></h1> |
211 |
<p>``Same scheme/host/port'' comparison algorithm is not correctly implemented |
212 |
yet.</p> |
213 |
<p>Test suite.</p> |
214 |
<p> |
215 |
</p> |
216 |
<hr /> |
217 |
<h1><a name="author">AUTHOR</a></h1> |
218 |
<p>Wakaba <<a href="mailto:w@suika.fam.cx">w@suika.fam.cx</a>></p> |
219 |
<p> |
220 |
</p> |
221 |
<hr /> |
222 |
<h1><a name="license">LICENSE</a></h1> |
223 |
<p>Copyright 2007-2008 Wakaba <<a href="mailto:w@suika.fam.cx">w@suika.fam.cx</a>></p> |
224 |
<p>This library is free software; you can redistribute it |
225 |
and/or modify it under the same terms as Perl itself.</p> |
226 |
|
227 |
</body> |
228 |
|
229 |
</html> |