Documentation for the A-A-P filetype detection module.

The filetype detection module can be used as a standalone program and from
within a Python program.


THE PROGRAM

Usage:
	Filetype.py [-I ruledir] ...  [-f rulefile] ... filename

This will print the filetype of "filename" on stdout.  When the type could not
be detected the result is "None".

The "-I ruledir" argument can be used to specify a directory to load *.afd
(Aap Filetype Detection) files from.  These add rules for filetype detection.
These are the default directories which are always scanned:

	/usr/local/share/aap/afd/
	~/.aap/afd/

The "-f rulefile" argument can be used to specify a file to load rules from.


DETECTION

Detection is done in this order:
   1. early python items
   2. check the extensions
   3. use the regular expressions
   4. check first line for a matching script name
   5. later python items

When on a non-Posix system, the file name is forced to be lower case, so that
case differences are ignored.  The rules must use lower case names for this
to work properly.  Rules with an upper case letter will only match on a Posix
system.


THE PYTHON MODULE

The ft_detect(fname) function can be called to detect the type of "fname".
A string with the detected file type is returned.  If the type is not
recognized, ft_detect() returns None.

For more info about the Filetype module, see the comments at the start of
Filetype.py.


FORMAT OF FILETYPE DETECTION RULES

These filetype detection lines are supported:

An empty line and a line starting with "#" is ignored.

suffix {suffix} {type}
			Add detection of a file type with a file name suffix.
			When a file name ends in .{suffix} it gets file type
			{type}.  {suffix} is taken literally, it is not a
			regular expression.
			When {type} is "ignore" file type detection is done on
			the file name with this suffix is removed.
			When {type} is "remove" a previously defined file type
			detection for {suffix} is removed.

regexp {regexp} {type} [append]
			Add detection of a file type with a Python regular
			expression.  When {regexp} matches with the name of a
			file it gets file type {type}.
			When {type} is "remove" a previously defined file type
			detection for {regexp} is removed.
			When "append" isn't given, the new detection is put
			before existing regexp detections, thus overruling
			them.  When "append" is used it is put after the
			existing regexp detections.

script {script} {type} [append]
			Add detection of a file type by examining the first
			line of the file.  When it starts with "#!" and
			{script} matches with the script program name it gets
			file type {type}.
			{script} is used as a Python regular expression.  It
			must match at the start of the program name.  Use
			".*" to ignore a path.  End with "$" to match at the
			end of the program name
			When {type} is "remove" a previously defined file type
			detection for {script} is removed.
			When "append" isn't given, the new detection is put
			before existing script detections.  When "append" is
			used the new detection is put after the existing
			script detections.

python [after] [append]
	python-code
			Add detection of a file type by executing Python code.
			The code is executed with the variable "fname" set to
			the name of the file.  When the code detects the file
			type it must assing it to the variable "type".
			When "after" isn't given, the detection is done before
			the suffix, regexp and script detection.  When
			"after" is given it's done last.
			When "append" isn't given, the new detection is put
			before existing python detections.  When "append" is
			used it is put after the existing python detections.

In the above the first argument can be put in quotes to include white space.
{type} can only consist of ASCII alphabetical characters, digits and
underscore.