whatpm/Whatpm/CacheManifest.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Whatpm::CacheManifest - An HTML5 Cache Manifest Parser</title>
<link rel="stylesheet" href="http://suika.fam.cx/www/style/html/pod.css" type="text/css" />
<link rev="made" href="mailto:admin@suika.fam.cx" />
</head>

<body>

<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->

<ul>

        <li><a href="#name">NAME</a></li>
        <li><a href="#synopsis">SYNOPSIS</a></li>
        <li><a href="#description">DESCRIPTION</a></li>
        <li><a href="#methods">METHODS</a></li>
        <li><a href="#manifest_data_structure">MANIFEST DATA STRUCTURE</a></li>
        <li><a href="#dependency">DEPENDENCY</a></li>
        <li><a href="#see_also">SEE ALSO</a></li>
        <li><a href="#todo">TODO</a></li>
        <li><a href="#author">AUTHOR</a></li>
        <li><a href="#license">LICENSE</a></li>
</ul>
<!-- INDEX END -->

<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>Whatpm::CacheManifest - An HTML5 Cache Manifest Parser</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
  use Whatpm::CacheManifest;
  
  my $manifest_uri = q&lt;<a href="http://www.example.com/manifest&gt">http://www.example.com/manifest&gt</a>;;
  my ($manifest_data, $manifest_base_uri)
      = some_function_to_retrieve_content ($manifest_uri);
  
  # or,
  
  my $manifest = Whatpm::CacheManifest-&gt;parse_byte_string
      ($manifest_data, $manifest_uri, $manifest_base_uri, sub {
        my %err = @_;
        warn $err{type}, &quot;\n&quot;;
      });
  
  $manifest_data = Encode::decode ('utf-8', $manifest_data);
  my $manifest = Whatpm::CacheManifest-&gt;parse_char_string
      ($manifest_data, $manifest_uri, $manifest_base_uri, sub {
        my %err = @_;
        warn $err{type}, &quot;\n&quot;;
      });
  
  # $manifest-&gt;[0]: Array reference of explicit URIs.
  # $manifest-&gt;[1]: Hash reference of fallback URIs.
  # $manifest-&gt;[2]: Array reference of online whitelist.</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>The <code>Whatpm::CacheManifest</code> module implements the parsing algorithm
for HTML5 cache manifest format, used to describe an offline Web
application.</p>
<p>
</p>
<hr />
<h1><a name="methods">METHODS</a></h1>
<p>This module provides two class methods to parse cache manifests:</p>
<dl>
<dt><strong><a name="item_parse_byte_string"><em>$manifest</em> = Whatpm::CacheManifest-&gt;parse_byte_string (<em>$manifest_bytes</em>, <em>$manifest_uri</em>, <em>$manifest_base_uri</em>, <em>$onerror</em>)</a></strong><br />
</dt>
<dt><strong><a name="item_parse_char_string"><em>$manifest</em> = Whatpm::CacheManifest-&gt;parse_char_string (<em>$manifest_chars</em>, <em>$manifest_uri</em>, <em>$manifest_base_uri</em>, <em>$onerror</em>)</a></strong><br />
</dt>
</dl>
<p>These methods parse a cache manifest and return that cache manifest
in the <a href="#manifest_data_structure">MANIFEST DATA STRUCTURE</a>.</p>
<p>Parameters:</p>
<dl>
<dt><strong><a name="item__24manifest_bytes"><em>$manifest_bytes</em></a></strong><br />
</dt>
<dd>
The content of the manifest files, as a Perl byte string.
It may or may not be a valid cache manifest.  It will be processed
as defined by HTML5 cache manifest parsing specification.
It will be interpreted as UTF-8 string, as defined in the specification.
</dd>
<p></p>
<dt><strong><a name="item__24manfiest_chars"><em>$manfiest_chars</em></a></strong><br />
</dt>
<dd>
The content of the manifest files, as a Perl character string.
It may or may not be a valid cache manifest.  It will be processed
as defined by HTML5 cache manifest parsing specification.  It may 
contain <code>U+0000</code> <code>NULL</code> characters; they are converted to
<code>U+FFFD</code> <code>REPLACEMENT CHARACTER</code>s as defined in the specification.
</dd>
<p></p>
<dt><strong><a name="item__24manifest_uri"><em>$manifest_uri</em></a></strong><br />
</dt>
<dd>
The IRI of the cache manifest.
</dd>
<p></p>
<dt><strong><a name="item__24manifest_base_uri"><em>$manifest_base_uri</em></a></strong><br />
</dt>
<dd>
The base IRI of the cache manifest.
</dd>
<p></p>
<dt><strong><a name="item__24onerror"><em>$onerror</em></a></strong><br />
</dt>
<dd>
The callback function that will be invoked if the manifest cache
has an error (or a warning).  It may be omitted.  If omitted, 
any error (or warning) is <code>warn</code>ed with its <code>type</code>.
</dd>
<dd>
<p>@@ TBW</p>
</dd>
<dd>
<p>For the list of the error types, see Whatpm Error Types
&lt;http://suika.fam.cx/gate/2005/sw/Whatpm%20Error%20Types&gt;.</p>
</dd>
<p></p></dl>
<p>In addition, a class method to check conformance of cache manifests
is provided:</p>
<dl>
<dt><strong><a name="item_check_manifest">Whatpm::CacheManifest-&gt;check_manifest (<em>$manifest</em>, <em>$onerror</em>)</a></strong><br />
</dt>
<dd>
Check conformance of a cache manifest, given as <em>$manifest</em>.
</dd>
<dl>
<dt><strong><a name="item__24manifest"><em>$manifest</em></a></strong><br />
</dt>
<dd>
The cache manifest to check, encoded in the <a href="#manifest_data_structure">MANIFEST DATA STRUCTURE</a>.
</dd>
<p></p>
<dt><strong><em>$onerror</em></strong><br />
</dt>
<dd>
The callback function that will be invoked if the manifest cache
has an error (or a warning).  It may be omitted.  If omitted, 
any error (or warning) is <code>warn</code>ed with its <code>type</code>.
</dd>
<dd>
<p>@@ TBW</p>
</dd>
<dd>
<p>For the list of the error types, see Whatpm Error Types
&lt;http://suika.fam.cx/gate/2005/sw/Whatpm%20Error%20Types&gt;.</p>
</dd>
<dd>
<p><code>index</code> is the index of the IRI with the error. @@ TBW</p>
</dd>
<p></p></dl>
<p>A cache manifest is conforming if (a) it is correctly labeled
as a cache manifest (e.g. as Internet media type <code>text/cache-manifest</code>)
in the transfer layer, (b) parsing the cache manifest by 
<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
with level <code>m</code> or <code>s</code>, and (c) checking the cache manifest by
<a href="#item_check_manifest"><code>check_manifest</code></a> raises no error with level <code>m</code> or <code>s</code>.</p>
</dl>
<p>
</p>
<hr />
<h1><a name="manifest_data_structure">MANIFEST DATA STRUCTURE</a></h1>
<p>If <em>$m</em> is in manifest data structure, <em>$m</em> is a reference to
the array with three items: <em>$explicit_uris</em>, <em>$fallback_uris</em>,
<em>$online_whitelist</em>, and <em>$manifest_uri</em>.</p>
<p><em>$explicit_uris</em> is a reference to the array, which
contains zero or more strings.  The strings are IRI references
of the explicit entries.</p>
<p><em>$fallback_uris</em> is a reference to the hash, which
contains zero or more mappings of strings (keys) to strings (values).
The keys are IRI references of the oppotunistic caching namespaces.
The values are IRI references of the fallback entries corresponding
to the oppotunistic caching namespaces.</p>
<p><em>$online_whitelist</em> is a reference to the array, which
contains zero or more strings.  The strings are IRI references
in the online whitelist.</p>
<p><em>$manfest_uri</em> is a string which is an IRI reference of the
manifest itself.</p>
<p>
</p>
<hr />
<h1><a name="dependency">DEPENDENCY</a></h1>
<p>This module depends on <a href="../Message/URI/URIReference.html">the Message::URI::URIReference manpage</a>, which is
part of the manakai-core package.</p>
<p>
</p>
<hr />
<h1><a name="see_also">SEE ALSO</a></h1>
<p>Whatpm Error Types
&lt;http://suika.fam.cx/gate/2005/sw/Whatpm%20Error%20Types&gt;.</p>
<p>HTML5
&lt;http://whatwg.org/html5&gt;.</p>
<p><a href="../Message/URI/URIReference.html">the Message::URI::URIReference manpage</a>
&lt;http://suika.fam.cx/www/manakai-core/lib/Message/URI/URIReference.html&gt;.</p>
<p>
</p>
<hr />
<h1><a name="todo">TODO</a></h1>
<p>``Same scheme/host/port'' comparison algorithm is not correctly implemented
yet.</p>
<p>Test suite.</p>
<p>
</p>
<hr />
<h1><a name="author">AUTHOR</a></h1>
<p>Wakaba &lt;<a href="mailto:w@suika.fam.cx">w@suika.fam.cx</a>&gt;</p>
<p>
</p>
<hr />
<h1><a name="license">LICENSE</a></h1>
<p>Copyright 2007-2008 Wakaba &lt;<a href="mailto:w@suika.fam.cx">w@suika.fam.cx</a>&gt;</p>
<p>This library is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.</p>

</body>

</html>
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&gt">http://www.example.com/manifest&gt</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>