whatpm/Whatpm/CacheManifest.pod

=head1 NAME

Whatpm::CacheManifest - An HTML5 Cache Manifest Parser

=head1 SYNOPSIS

  use Whatpm::CacheManifest;
  
  my $manifest_uri = q<http://www.example.com/manifest>;
  my ($manifest_data, $manifest_base_uri)
      = some_function_to_retrieve_content ($manifest_uri);
  
  # or,
  
  my $manifest = Whatpm::CacheManifest->parse_byte_string
      ($manifest_data, $manifest_uri, $manifest_base_uri, sub {
        my %err = @_;
        warn $err{type}, "\n";
      });
  
  $manifest_data = Encode::decode ('utf-8', $manifest_data);
  my $manifest = Whatpm::CacheManifest->parse_char_string
      ($manifest_data, $manifest_uri, $manifest_base_uri, sub {
        my %err = @_;
        warn $err{type}, "\n";
      });
  
  # $manifest->[0]: Array reference of explicit URIs.
  # $manifest->[1]: Hash reference of fallback URIs.
  # $manifest->[2]: Array reference of online whitelist.

=head1 DESCRIPTION

The C<Whatpm::CacheManifest> module implements the parsing algorithm
for HTML5 cache manifest format, used to describe an offline Web
application.

=head1 METHODS

This module provides two class methods to parse cache manifests:

=over 4

=item I<$manifest> = Whatpm::CacheManifest->parse_byte_string (I<$manifest_bytes>, I<$manifest_uri>, I<$manifest_base_uri>, I<$onerror>)

=item I<$manifest> = Whatpm::CacheManifest->parse_char_string (I<$manifest_chars>, I<$manifest_uri>, I<$manifest_base_uri>, I<$onerror>)

=back

These methods parse a cache manifest and return that cache manifest
in the L<MANIFEST DATA STRUCTURE>.

Parameters:

=over 4

=item I<$manifest_bytes>

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.

=item I<$manfiest_chars>

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 C<U+0000> C<NULL> characters; they are converted to
C<U+FFFD> C<REPLACEMENT CHARACTER>s as defined in the specification.

=item I<$manifest_uri>

The IRI of the cache manifest.

=item I<$manifest_base_uri>

The base IRI of the cache manifest.

=item I<$onerror>

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 C<warn>ed with its C<type>.

@@ TBW

For the list of the error types, see Whatpm Error Types
<http://suika.fam.cx/gate/2005/sw/Whatpm%20Error%20Types>.

=back

In addition, a class method to check conformance of cache manifests
is provided:

=over 4

=item Whatpm::CacheManifest->check_manifest (I<$manifest>, I<$onerror>)

Check conformance of a cache manifest, given as I<$manifest>.

=over 4

=item I<$manifest>

The cache manifest to check, encoded in the L<MANIFEST DATA STRUCTURE>.

=item I<$onerror>

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 C<warn>ed with its C<type>.

@@ TBW

For the list of the error types, see Whatpm Error Types
<http://suika.fam.cx/gate/2005/sw/Whatpm%20Error%20Types>.

C<index> is the index of the IRI with the error. @@ TBW

=back

A cache manifest is conforming if (a) it is correctly labeled
as a cache manifest (e.g. as Internet media type C<text/cache-manifest>)
in the transfer layer, (b) parsing the cache manifest by 
C<parse_byte_string> or C<parse_char_string> raises no error
with level C<m> or C<s>, and (c) checking the cache manifest by
C<check_manifest> raises no error with level C<m> or C<s>.

=back

=head1 MANIFEST DATA STRUCTURE

If I<$m> is in manifest data structure, I<$m> is a reference to
the array with three items: I<$explicit_uris>, I<$fallback_uris>,
I<$online_whitelist>, and I<$manifest_uri>.

I<$explicit_uris> is a reference to the array, which
contains zero or more strings.  The strings are IRI references
of the explicit entries.

I<$fallback_uris> 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.

I<$online_whitelist> is a reference to the array, which
contains zero or more strings.  The strings are IRI references
in the online whitelist.

I<$manfest_uri> is a string which is an IRI reference of the
manifest itself.

=head1 DEPENDENCY

This module depends on L<Message::URI::URIReference>, which is
part of the manakai-core package.

=head1 SEE ALSO

Whatpm Error Types
<http://suika.fam.cx/gate/2005/sw/Whatpm%20Error%20Types>.

HTML5
<http://whatwg.org/html5>.

L<Message::URI::URIReference>
<http://suika.fam.cx/www/manakai-core/lib/Message/URI/URIReference.html>.

=head1 TODO

"Same scheme/host/port" comparison algorithm is not correctly implemented
yet.

Test suite.

=head1 AUTHOR

Wakaba <w@suika.fam.cx>

=head1 LICENSE

Copyright 2007-2008 Wakaba <w@suika.fam.cx>

This library is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.

=cut

# $Date: 2007/11/04 11:49:44 $

1	=head1 NAME
2
3	Whatpm::CacheManifest - An HTML5 Cache Manifest Parser
4
5	=head1 SYNOPSIS
6
7	use Whatpm::CacheManifest;
8
9	my $manifest_uri = q<http://www.example.com/manifest>;
10	my ($manifest_data, $manifest_base_uri)
11	= some_function_to_retrieve_content ($manifest_uri);
12
13	# or,
14
15	my $manifest = Whatpm::CacheManifest->parse_byte_string
16	($manifest_data, $manifest_uri, $manifest_base_uri, sub {
17	my %err = @_;
18	warn $err{type}, "\n";
19	});
20
21	$manifest_data = Encode::decode ('utf-8', $manifest_data);
22	my $manifest = Whatpm::CacheManifest->parse_char_string
23	($manifest_data, $manifest_uri, $manifest_base_uri, sub {
24	my %err = @_;
25	warn $err{type}, "\n";
26	});
27
28	# $manifest->[0]: Array reference of explicit URIs.
29	# $manifest->[1]: Hash reference of fallback URIs.
30	# $manifest->[2]: Array reference of online whitelist.
31
32	=head1 DESCRIPTION
33
34	The C<Whatpm::CacheManifest> module implements the parsing algorithm
35	for HTML5 cache manifest format, used to describe an offline Web
36	application.
37
38	=head1 METHODS
39
40	This module provides two class methods to parse cache manifests:
41
42	=over 4
43
44	=item I<$manifest> = Whatpm::CacheManifest->parse_byte_string (I<$manifest_bytes>, I<$manifest_uri>, I<$manifest_base_uri>, I<$onerror>)
45
46	=item I<$manifest> = Whatpm::CacheManifest->parse_char_string (I<$manifest_chars>, I<$manifest_uri>, I<$manifest_base_uri>, I<$onerror>)
47
48	=back
49
50	These methods parse a cache manifest and return that cache manifest
51	in the L<MANIFEST DATA STRUCTURE>.
52
53	Parameters:
54
55	=over 4
56
57	=item I<$manifest_bytes>
58
59	The content of the manifest files, as a Perl byte string.
60	It may or may not be a valid cache manifest. It will be processed
61	as defined by HTML5 cache manifest parsing specification.
62	It will be interpreted as UTF-8 string, as defined in the specification.
63
64	=item I<$manfiest_chars>
65
66	The content of the manifest files, as a Perl character string.
67	It may or may not be a valid cache manifest. It will be processed
68	as defined by HTML5 cache manifest parsing specification. It may
69	contain C<U+0000> C<NULL> characters; they are converted to
70	C<U+FFFD> C<REPLACEMENT CHARACTER>s as defined in the specification.
71
72	=item I<$manifest_uri>
73
74	The IRI of the cache manifest.
75
76	=item I<$manifest_base_uri>
77
78	The base IRI of the cache manifest.
79
80	=item I<$onerror>
81
82	The callback function that will be invoked if the manifest cache
83	has an error (or a warning). It may be omitted. If omitted,
84	any error (or warning) is C<warn>ed with its C<type>.
85
86	@@ TBW
87
88	For the list of the error types, see Whatpm Error Types
89	<http://suika.fam.cx/gate/2005/sw/Whatpm%20Error%20Types>.
90
91	=back
92
93	In addition, a class method to check conformance of cache manifests
94	is provided:
95
96	=over 4
97
98	=item Whatpm::CacheManifest->check_manifest (I<$manifest>, I<$onerror>)
99
100	Check conformance of a cache manifest, given as I<$manifest>.
101
102	=over 4
103
104	=item I<$manifest>
105
106	The cache manifest to check, encoded in the L<MANIFEST DATA STRUCTURE>.
107
108	=item I<$onerror>
109
110	The callback function that will be invoked if the manifest cache
111	has an error (or a warning). It may be omitted. If omitted,
112	any error (or warning) is C<warn>ed with its C<type>.
113
114	@@ TBW
115
116	For the list of the error types, see Whatpm Error Types
117	<http://suika.fam.cx/gate/2005/sw/Whatpm%20Error%20Types>.
118
119	C<index> is the index of the IRI with the error. @@ TBW
120
121	=back
122
123	A cache manifest is conforming if (a) it is correctly labeled
124	as a cache manifest (e.g. as Internet media type C<text/cache-manifest>)
125	in the transfer layer, (b) parsing the cache manifest by
126	C<parse_byte_string> or C<parse_char_string> raises no error
127	with level C<m> or C<s>, and (c) checking the cache manifest by
128	C<check_manifest> raises no error with level C<m> or C<s>.
129
130	=back
131
132	=head1 MANIFEST DATA STRUCTURE
133
134	If I<$m> is in manifest data structure, I<$m> is a reference to
135	the array with three items: I<$explicit_uris>, I<$fallback_uris>,
136	I<$online_whitelist>, and I<$manifest_uri>.
137
138	I<$explicit_uris> is a reference to the array, which
139	contains zero or more strings. The strings are IRI references
140	of the explicit entries.
141
142	I<$fallback_uris> is a reference to the hash, which
143	contains zero or more mappings of strings (keys) to strings (values).
144	The keys are IRI references of the oppotunistic caching namespaces.
145	The values are IRI references of the fallback entries corresponding
146	to the oppotunistic caching namespaces.
147
148	I<$online_whitelist> is a reference to the array, which
149	contains zero or more strings. The strings are IRI references
150	in the online whitelist.
151
152	I<$manfest_uri> is a string which is an IRI reference of the
153	manifest itself.
154
155	=head1 DEPENDENCY
156
157	This module depends on L<Message::URI::URIReference>, which is
158	part of the manakai-core package.
159
160	=head1 SEE ALSO
161
162	Whatpm Error Types
163	<http://suika.fam.cx/gate/2005/sw/Whatpm%20Error%20Types>.
164
165	HTML5
166	<http://whatwg.org/html5>.
167
168	L<Message::URI::URIReference>
169	<http://suika.fam.cx/www/manakai-core/lib/Message/URI/URIReference.html>.
170
171	=head1 TODO
172
173	"Same scheme/host/port" comparison algorithm is not correctly implemented
174	yet.
175
176	Test suite.
177
178	=head1 AUTHOR
179
180	Wakaba <w@suika.fam.cx>
181
182	=head1 LICENSE
183
184	Copyright 2007-2008 Wakaba <w@suika.fam.cx>
185
186	This library is free software; you can redistribute it
187	and/or modify it under the same terms as Perl itself.
188
189	=cut
190
191	# $Date: 2007/11/04 11:49:44 $
192