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:

• AddType - Filename suffix mappings to MIME Content-Types
• AddEncoding - Filename suffix mappings to MIME Content-Encodings
• AddLanguage - Multi language support, suffix mappings to different Content-Languages

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:

suffix

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.

representation

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.

encoding

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.

quality

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.

Examples

	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

Example

	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

Examples

	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]

Example

	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

Proxies can be set up as follows:

	Proxy		scheme	proxy

And the parameters are:

scheme

The first part of a URL, for example http, ftp, or gopher. Remember that access schemes are case sensitive!

proxy

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!

Examples

	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

Gateways can be set much like proxies:

	Gateway		scheme	gateway

Examples

	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:

• Map - Map URLs to actual files
• Pass - Accept a request
• Fail - Fail a request

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,

• Rules are scanned from the top of the file to the bottom.
• If a request matches a Map template exactly, the result string is used instead of the original string and applied to successive rules.
• If the request matches a Map template with wild card, then the text of the request which matches the wild card is inserted in place of the wild card in the result string to form the translated request. If the result string has no wild card, it is used as it is.
• When a Map substitution takes place, the rule scan continues with the next rule using the new string in place of the request. This is not the case if a Pass or Fail is matched: they terminate the rule scan.