NAME

HTTP::Browscap - Parse and search browscap.ini files

SYNOPSIS

    use HTTP::Browscap;

    my $capable = browscap();

    if( $capable->{wap} ) {
        output_WAP();
    }

    if( $capable->{css} > 1 ) {
        # Browser can handle CSS2
    }

    # OO interface
    my $BC = HTTP::Browscap->new( 'browscap.ini' );

    $capable = $BC->match( $ENV{HTTP_USER_AGENT} );

ABSTRACT

Browscap.ini is a file, introduced with Microsoft's IIS, that lists the User-Agent strings that different browsers send, and various capabilities of those browsers. This module parses browscap.ini and allows you to find the capability definitions for a given browser.

DESCRIPTION

Starting with Microsoft's IIS, a browscap.ini file was used to list the capabilities of various browsers. Using the User-Agent header sent by a browser during each HTTP request, the capabilities of a browser are retrieved. If an exact match of the User-Agent string isn't found, wild-card expantion is done. If all fails, a default browser definition is used.

The information in Browscap allows you to adapt your response to the browser's capabalities. There are however limits it's usefulness. It only detects if a browser has a certain capability, but not if this capability has been deactivated nor if it's badly implemented. In particular, most CSS and JavaScript implementations will make you scream. You might want to use HTTP::BrowserDetect or HTTP::BrowserSupport to detect a specific feature or bug.

Capabilities

The browser capability definition returned by "browscap" or "match" is a hash reference. The keys are defined below. Boolean capabilites can have values '' (false) or 1 (true).

Microsoft defines the following capabilities :

activexcontrols

Browser supports ActiveX controls? Boolean.

backgroundsounds

Browser supports background sounds? Boolean.

beta

Is this a beta version of the browser? Boolean.

browser

String containing a useful name for the browser.

cdf

Does the browser support Channel Definition Format for Webcasting? Boolean.

cookies

Does the browser support cookies? Note that this does not mean that the browser has cookie support currently turned on. Boolean.

frames

Does the browser support HTML <FRAMESET> and <FRAME> tags? Boolean.

javaapplets

Does the browser support Java applets? Note that even if this is true, the user could have Java turned off. Boolean.

javascript

Does the browser support javascript? Note that even if this is true, the user could have javascript turned off. Boolean.

platform

Which platform (ie, OS) is the browser running on. Example : WinNT, WinXP, Win2003, Palm, Linux, Debian.

If you want a list of all possible values, run the following on your browscap.ini file :

    grep platform= browscap.ini | sort | uniq

tables

Does the browser support HTML <TABLE> tags? Boolean.

vbscript

Does the browser support VBscript? Note that even if this is true, the user should have VBscript turned off. Boolean.

version

Full version number of the browser. Example: 1.10

Gary Keith adds the following:

alpha: Browser is an alpha version and still under development? Boolean.
aol: Is this an AOL-branded browser? Boolean.
aolversion: A number indicating what version, if any, of the America Online browser is being used.
crawler: Is this browser in fact a web-crawler or spider, often sent by a search engine? Boolean.
cssversion: CSS version supported by this browser. Possible values : 0 (no CSS support), 1 or 2.
cssversion: Same as above.
supportcss: Does this user-agent support CSS? Boolean.
iframes: Does the browser support MS's <IFRAME> tags? Boolean.
isbanned: Is the user-agent string banned by Gary Keith? Boolean.
ismobiledevice: Is this a browser on a mobile device (iPhone, Blackberry, etc)? Boolean.
issyndicationreader: Is this user-agent an RSS or ATOM reader? Boolean.
netclr: Is this a .NET CLR user-agent? Boolean. (Seems to longer exist.)
majorver: Major version number. Example: given a version of 1.10, majorver is 1.
minorver: Minor version number. Example: given a version of 1.10, minorver is 10.
stripper: Identifies the browser as a crawler that does not obey robots.txt. This includes e-mail harvesters, download managers and so on. Boolean.
tables: Does the browser support HTML <TABLE> tags? Boolean.
wap: Is browser a WAP-enabled mobile phone? Boolean.
win16: Is this the 16-bit windows version of the browser? Detecting this might be useful if you want the user to save a file with 8.3 length. Boolean.
win32: Is this the 32-bit windows version of the browser? Boolean.
win64: Is this the 32-bit windows version of the browser? Boolean.

HTTP::Browscap adds the following:

UA: Full text of the User-Agent string used to match this definition.
LINE: Line in browscap.ini where the browser's capabilites are defined. Useful for debuging.
FALLBACK: If fallback was needed to match a UA string, this contains what was modified to make the match. Can be one of browser, OS or browser+OS.

The browscap.ini standard also defines parent, which is a link to another capability list that complements the current definition. HTTP::Browscap handles these internaly, so that you only have to do one lookup.

Note that, contrary to other implementations, all capability names are in lower case, except for UA and LINE. This means you should look for 'win16' instead of 'Win16'.

Cached data

Because parsing browscap.ini is slow, a cached version of the parsed data is automatically created and used where possible. Normaly this cached version is created when you ran browscap-update during installation.

The cache file is a MLDBM file created with DB_File and Storable. You may change this by overloading "__save_cache" and "__open_cache".

UPDATING browscap.ini

You will want to periodically fetch a new browscap.ini. This can be done with the following :

    wget -O browscap.ini \
        "http://browsers.garykeith.com/stream.asp?BrowsCapINI"
    browscap-update browscap.ini
    rm browscap.ini

However, you must read http://browsers.garykeith.com/terms.asp before automating this.

FUNCTIONS

browscap

    $def = browscap();
    $def = browscap( $ua );

Find the capabilities of a browser identified by a given User-Agent string. If the string is missing, browscap will attempt to find one. See __guess_ua below.

Returns a hashref. See "Capabilities" above.

METHODS

There is also an object oriented interface to this module.

new

    my $BC = HTTP::Browscap->new;
    my $BC = HTTP::Browscap->new( $ini_file, $fallback );

Creates a new browscap object. If you do not specify $ini_file, the system's browscap.ini will be used.

If $fallback is true, an attempt is made to make unknown versions of Windows, Firefox, IE and Opera match the most recent known versions. That is IE 24.8 (if/when it is released) should match IE 9.0 (currenty most recent as of this writing).

Default is true.

match

    $def = $BC->match;
    $def = $BC->match( $ua );

Find the capabilities of a browser identified by the User-Agent string given in $ua. If the string is missing, match will attempt to find one. See "__guess_ua" below.

Returns a hashref. See "Capabilities" above.

open

    $BC->open

Parse and load the browscap.ini file. If there is a cache-file present and it is more recent then browscap.ini, the cache-file is used instead. Creates the cache file if possible

This method is called automatically when needed. You should only call this yourself when you want to create a cache file but not bother with matching.

OVERLOADING METHODS

The following methods are documented in case you wish to create a sub-class.

__guess_ua

    $BC->__guess_ua;

Used to guess at a User-Agent string. First "__guess_ua" looks in $ENV{HTTP_USER_AGENT} (CGI environement variable). If this fails and $ENV{MOD_PERL} is set, __guess_ua will use the mod_perl's "headers_in()" in Apache to find it. If both these fails, the default User-Agent is returned, which is probably not what you want.

Returns the User-Agent string.

__set_file

    $BC->__set_file( $file );

Called to set a new browscap.ini file. This method set's data members, generates the new cache-file name based on $file and clears any parsed data from memory.

__save_cache

Saves the parsed browscap.ini file (which is in {data}) to the cache file named {cache}.

Returns true on success.

Returns false on failure, with $! set accordingly.

__open_cache

Called to open the cache {cache} and tie it to {data}.

Returns true on success. Dies on failure.

__parse

Load and parse the browscap.ini file. You will have to read the source code if you want to modify it.

__parse_wild

Converts a UA string from browscap.ini to a Perl patern. The UA strings in browscap.ini may contain * or ., which act like file-globs.

AUTHOR

Philip Gwyn, <gwyn-AT-cpan.org>

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

To install HTTP::Browscap, copy and paste the appropriate command in to your terminal.

cpanm

cpanm HTTP::Browscap

CPAN shell

perl -MCPAN -e shell
install HTTP::Browscap

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)