W3C libwww Using

Rule File Syntax

This section described the syntax of a rule file as supported by the Rule File Filter in libwww. Please read the section on Rule Files for a full description of the rule file API.

File Suffix Bindings

The W3C Sample Code Library can use suffixes to discover the content-type, content-encoding and content-language of a file. The Library contains a long list of commonly used file suffix types but the application doesn't have to use this. In any case, the following configuration directives can be used to add new suffix bindings and override existing defaults:

Binding Suffixes to MIME Content-Types

As well as any mapping lines in the rule file, the rule file may be used to define the data types of files with particular suffixes. The Library has an extensive set of predefined suffixes, but applications do not need to use this. The syntax is:

	AddType .suffix representation encoding [quality]

The parameters are as follows:

The last part of the filename. There are two special cases. *.* matches to all files which have not been matched by any explicit suffixes but do contain a file suffix delimiter. A file suffix delimiter is often a dot <.> but it can be defined as an arbitrary character, please see the Suffix Binding Module for details. * by itself matches to any file which does not match any other suffix.

A MIME Content-Type style description of the representation in fact in use in the file. See the HTTP spec. This need not be a real MIME type - it will only be used if it matches a type given by a client.

A MIME content transfer encoding type. Much more limited in variety than representations, basically whether the file is ASCII (7bit or 8bit) or binary. A few other encodings are allowed, and maybe extension to compression.

Optional. A floating point number between 0.0 and 1.0 which determines the relative merits of files xxx.* which differ in their suffix only, when a link to xxx.multi is being resolved. User to 1.0.


	AddType	.html	text/html		8bit	1.0
	AddType	.text	text/plain		7bit	0.9
	AddType	.ps	application/postscript	8bit	1.0
	AddType	*.*	application/binary	binary	0.1
	AddType	*	text/plain		7bit

Binding Suffixes to MIME Content-Encodings

Suffixes are also used to determine the Content-Encoding of a file (.Z suffix for x-compressed, for example). Syntax is:

	AddEncoding .suffix  encoding


	AddEncoding .Z  x-compress

Multi language Support

Multi language support is also built on using suffixes to determine the language of a document. Suffix is bound to a language by AddLanguage rule (.en suffix for English, for example). Syntax is:

	AddLanguage .suffix  encoding


	AddLanguage	.en	en
	AddLanguage	.dk	dk

External Viewers and Presenters

In order to expand the set of content types that can be handled by an application, you can specify a set of external viewers which can handle specific content types. This is for example often the case for postscript viewers etc. This is quite similar to a mail cap file, but the Library doesn't have a real Mail cap file parser.

	Presentation representation command [quality]


	Presentation application/postscript	ghostview	0.5

Proxy Servers and Gateways

You can also specify proxies and gateway using the Library rule file. You can lao read more about how libwww handles proxies and gateways in the User's Guide.


Proxies can be set up as follows:

	Proxy		scheme	proxy

And the parameters are:

The first part of a URL, for example http, ftp, or gopher. Remember that access schemes are case sensitive!
A full URL specifying where the application can go in order to access the resource. When saying a full URL, it means that you must use the normal URL syntax as specified by RFC 1831. Note in the example below that the access scheme differs from the scheme we want to proxy!


	Proxy	http	http://proxy.foo.com:8000/
	Proxy	ftp	http://proxy.foo.com:8000/
	Proxy	gopher	http://proxy.foo.com:8000/

You can also specify a set of domains where we shouldn't go via a proxy server even though the rules indicated by the proxy directive above indicates that we should. Often you want to be able to handle a few exceptions from the proxy rule - especially if the remote host is either very close or on a high bandwidth connection.

	NoProxy		hostname	scheme	port

Registers a host name or a domain as a place where no proxy should be contacted - for example a very fast link. If port is not indicated then it applies to all ports.


Gateways can be set much like proxies:

	Gateway		scheme	gateway


	Gateway	wais	http://www.w3.org:8001/

URL Mapping Rules

Rules define the mapping between virtual URLs and physical file names. Currently the following rules are understood:

Mapping, Passing and Failing

There are three main rules: Map, Pass and Fail. The server uses the top rule first, then each successive rule unless told otherwise by a Pass or a Fail rule.

Map template result
If the address matches the template, use the result string from now on for future rules.
Pass template
If the address matches the template, use it as it is, processing no further rules.
Pass template result
If the string matches the template, use the result string as it is, processing no further rules.
Fail template
If the address matches the template, prohibit access, processing no further rules.

When matching,

Henrik Frystyk Nielsen,
@(#) $Id: RuleSyntax.html,v 1.9 1999/01/26 13:55:47 frystyk Exp $