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	wakaba	1.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	wakaba	1.2	The cache manifest to check, encoded in the <a href="#manifest_data_structure">MANIFEST DATA STRUCTURE</a>.
144	wakaba	1.1	</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	wakaba	1.2	<dd>
161			<p><code>index</code> is the index of the IRI with the error. @@ TBW</p>
162			</dd>
163	wakaba	1.1	<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	wakaba	1.2	<em>$online_whitelist</em>, and <em>$manifest_uri</em>.</p>
178	wakaba	1.1	<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	wakaba	1.2	<p><em>$manfest_uri</em> is a string which is an IRI reference of the
190			manifest itself.</p>
191	wakaba	1.1	<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	wakaba	1.2	part of the manakai-core package.</p>
197	wakaba	1.1	<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	wakaba	1.2	<p>Test suite.</p>
214	wakaba	1.1	<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	wakaba	1.2	<p>Copyright 2007-2008 Wakaba <<a href="mailto:w@suika.fam.cx">w@suika.fam.cx</a>></p>
224	wakaba	1.1	<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>