NAME

Whatpm::CacheManifest - An HTML5 Cache Manifest Parser

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.

DESCRIPTION

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

METHODS

This module provides two class methods to parse cache manifests:

$manifest = Whatpm::CacheManifest->parse_byte_string ($manifest_bytes, $manifest_uri, $manifest_base_uri, $onerror)
$manifest = Whatpm::CacheManifest->parse_char_string ($manifest_chars, $manifest_uri, $manifest_base_uri, $onerror)

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

Parameters:

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

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

$manifest_uri
The IRI of the cache manifest.

$manifest_base_uri
The base IRI of the cache manifest.

$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 warned with its type.

@@ TBW

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

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

Whatpm::CacheManifest->check_manifest ($manifest, $onerror)
Check conformance of a cache manifest, given as $manifest.
$manifest
The cache manifest to check, in the MANIFEST DATA STRUCTURE.

$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 warned with its type.

@@ TBW

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

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

MANIFEST DATA STRUCTURE

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

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

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

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

DEPENDENCY

This module depends on the Message::URI::URIReference manpage, which is part of manakai.

SEE ALSO

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

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

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

TODO

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

AUTHOR

Wakaba <w@suika.fam.cx>

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.