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, 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>
<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>,
and <em>$online_whitelist</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>
</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 manakai.</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>
</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 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			The cache manifest to check, 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			<p></p></dl>
161			<p>A cache manifest is conforming if (a) it is correctly labeled
162			as a cache manifest (e.g. as Internet media type <code>text/cache-manifest</code>)
163			in the transfer layer, (b) parsing the cache manifest by
164			<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
165			with level <code>m</code> or <code>s</code>, and (c) checking the cache manifest by
166			<a href="#item_check_manifest"><code>check_manifest</code></a> raises no error with level <code>m</code> or <code>s</code>.</p>
167			</dl>
168			<p>
169			</p>
170			<hr />
171			<h1><a name="manifest_data_structure">MANIFEST DATA STRUCTURE</a></h1>
172			<p>If <em>$m</em> is in manifest data structure, <em>$m</em> is a reference to
173			the array with three items: <em>$explicit_uris</em>, <em>$fallback_uris</em>,
174			and <em>$online_whitelist</em>.</p>
175			<p><em>$explicit_uris</em> is a reference to the array, which
176			contains zero or more strings. The strings are IRI references
177			of the explicit entries.</p>
178			<p><em>$fallback_uris</em> is a reference to the hash, which
179			contains zero or more mappings of strings (keys) to strings (values).
180			The keys are IRI references of the oppotunistic caching namespaces.
181			The values are IRI references of the fallback entries corresponding
182			to the oppotunistic caching namespaces.</p>
183			<p><em>$online_whitelist</em> is a reference to the array, which
184			contains zero or more strings. The strings are IRI references
185			in the online whitelist.</p>
186			<p>
187			</p>
188			<hr />
189			<h1><a name="dependency">DEPENDENCY</a></h1>
190			<p>This module depends on <a href="../Message/URI/URIReference.html">the Message::URI::URIReference manpage</a>, which is
191			part of manakai.</p>
192			<p>
193			</p>
194			<hr />
195			<h1><a name="see_also">SEE ALSO</a></h1>
196			<p>Whatpm Error Types
197			<http://suika.fam.cx/gate/2005/sw/Whatpm%20Error%20Types>.</p>
198			<p>HTML5
199			<http://whatwg.org/html5>.</p>
200			<p><a href="../Message/URI/URIReference.html">the Message::URI::URIReference manpage</a>
201			<http://suika.fam.cx/www/manakai-core/lib/Message/URI/URIReference.html>.</p>
202			<p>
203			</p>
204			<hr />
205			<h1><a name="todo">TODO</a></h1>
206			<p>``Same scheme/host/port'' comparison algorithm is not correctly implemented
207			yet.</p>
208			<p>
209			</p>
210			<hr />
211			<h1><a name="author">AUTHOR</a></h1>
212			<p>Wakaba <<a href="mailto:w@suika.fam.cx">w@suika.fam.cx</a>></p>
213			<p>
214			</p>
215			<hr />
216			<h1><a name="license">LICENSE</a></h1>
217			<p>Copyright 2007 Wakaba <<a href="mailto:w@suika.fam.cx">w@suika.fam.cx</a>></p>
218			<p>This library is free software; you can redistribute it
219			and/or modify it under the same terms as Perl itself.</p>
220
221			</body>
222
223			</html>