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, 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>.

=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>,
and I<$online_whitelist>.

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.

=head1 DEPENDENCY

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

=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.

=head1 AUTHOR

Wakaba <w@suika.fam.cx>

=head1 LICENSE

Copyright 2007 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/08/06 10:56:50 $

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			The cache manifest to check, in the L<MANIFEST DATA STRUCTURE>.
107
108			=item I<$onerror>
109
110
111			The callback function that will be invoked if the manifest cache
112			has an error (or a warning). It may be omitted. If omitted,
113			any error (or warning) is C<warn>ed with its C<type>.
114
115			@@ TBW
116
117			For the list of the error types, see Whatpm Error Types
118			<http://suika.fam.cx/gate/2005/sw/Whatpm%20Error%20Types>.
119
120			=back
121
122			A cache manifest is conforming if (a) it is correctly labeled
123			as a cache manifest (e.g. as Internet media type C<text/cache-manifest>)
124			in the transfer layer, (b) parsing the cache manifest by
125			C<parse_byte_string> or C<parse_char_string> raises no error
126			with level C<m> or C<s>, and (c) checking the cache manifest by
127			C<check_manifest> raises no error with level C<m> or C<s>.
128
129			=back
130
131			=head1 MANIFEST DATA STRUCTURE
132
133			If I<$m> is in manifest data structure, I<$m> is a reference to
134			the array with three items: I<$explicit_uris>, I<$fallback_uris>,
135			and I<$online_whitelist>.
136
137			I<$explicit_uris> is a reference to the array, which
138			contains zero or more strings. The strings are IRI references
139			of the explicit entries.
140
141			I<$fallback_uris> is a reference to the hash, which
142			contains zero or more mappings of strings (keys) to strings (values).
143			The keys are IRI references of the oppotunistic caching namespaces.
144			The values are IRI references of the fallback entries corresponding
145			to the oppotunistic caching namespaces.
146
147			I<$online_whitelist> is a reference to the array, which
148			contains zero or more strings. The strings are IRI references
149			in the online whitelist.
150
151			=head1 DEPENDENCY
152
153			This module depends on L<Message::URI::URIReference>, which is
154			part of manakai.
155
156			=head1 SEE ALSO
157
158			Whatpm Error Types
159			<http://suika.fam.cx/gate/2005/sw/Whatpm%20Error%20Types>.
160
161			HTML5
162			<http://whatwg.org/html5>.
163
164			L<Message::URI::URIReference>
165			<http://suika.fam.cx/www/manakai-core/lib/Message/URI/URIReference.html>.
166
167			=head1 TODO
168
169			"Same scheme/host/port" comparison algorithm is not correctly implemented
170			yet.
171
172			=head1 AUTHOR
173
174			Wakaba <w@suika.fam.cx>
175
176			=head1 LICENSE
177
178			Copyright 2007 Wakaba <w@suika.fam.cx>
179
180			This library is free software; you can redistribute it
181			and/or modify it under the same terms as Perl itself.
182
183			=cut
184
185			# $Date: 2007/08/06 10:56:50 $
186