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	wakaba	1.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	wakaba	1.2	The cache manifest to check, encoded in the L<MANIFEST DATA STRUCTURE>.
107	wakaba	1.1
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	wakaba	1.2	C<index> is the index of the IRI with the error. @@ TBW
120
121	wakaba	1.1	=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	wakaba	1.2	I<$online_whitelist>, and I<$manifest_uri>.
137	wakaba	1.1
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	wakaba	1.2	I<$manfest_uri> is a string which is an IRI reference of the
153			manifest itself.
154
155	wakaba	1.1	=head1 DEPENDENCY
156
157			This module depends on L<Message::URI::URIReference>, which is
158	wakaba	1.2	part of the manakai-core package.
159	wakaba	1.1
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	wakaba	1.2	Test suite.
177
178	wakaba	1.1	=head1 AUTHOR
179
180			Wakaba <w@suika.fam.cx>
181
182			=head1 LICENSE
183
184	wakaba	1.2	Copyright 2007-2008 Wakaba <w@suika.fam.cx>
185	wakaba	1.1
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	wakaba	1.2	# $Date: 2007/11/04 11:49:44 $
192	wakaba	1.1