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 <[email protected]>

=head1 LICENSE

Copyright 2007 Wakaba <[email protected]>

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	=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 <[email protected]>
175
176	=head1 LICENSE
177
178	Copyright 2007 Wakaba <[email protected]>
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