uaparser_gleam

• code :: https://github.com/halostatue/uaparser_gleam
• issues :: https://github.com/halostatue/uaparser_gleam/issues

uaparser is a User Agent parser implementation generated from the BrowserScope collection of core regular expressions. This is primarily generated code from the regular expressions, including unit tests.

Installation

gleam add uaparser_gleam@1

import uaparser

pub fn main() {
  let ua = uaparser.parse_user_agent(
    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
  )
  // ua.family == "Chrome"
  // ua.version == Some(Version(major: "120", minor: Some("0"), patch: Some("0")))
}

Further documentation can be found at https://hexdocs.pm/uaparser_gleam.

Development

The parser code is generated from ua-parser/uap-core regular expressions. The uap-core repository must be cloned locally before running the generator.

A Justfile is provided for common tasks:

just generate  # Clone uap-core (if needed) and regenerate parser + tests
just test      # Generate and run tests on both Erlang and JavaScript targets
just bench     # Run benchmarks

Or manually:

git clone https://github.com/ua-parser/uap-core.git uap-core
gleam run -m generate_uaparser  # Generate uaparser from ua-parser/uap-core
gleam test                      # Run the tests

Optimizations

There are two optimizations implemented in uaparser to improve performance of User Agent parsing.

The first is to compile and cache all of the regular expressions (there are 431 regular expressions in uap-core in April 2026). This shows a 2.2–2.4x improvement on a weighted benchmark¹ over ten User Agent strings. On individual User Agent patterns benchmarks², it shows as much as 3x improvement.

The second is to use predictive dispatching to reduce the number of regular expressions that must be matched for resolution in the typical cases. With at most three string containment tests, the number of regular expressions that must be tested for a match is reduced by a significant fraction, as shown by the pseudo-Typescript below.

function find_ua(ua: string) {
  if (ua.includes("Chrome/")) {
    if (ua.includes(" Mobile")) {
      return chrome_mobile.find(ua); // 88 patterns
    }

    return chrome_desktop.find(ua); // 127 patterns
  }

  if (ua.includes("Firefox/")) {
    return firefox.find(ua); // 120 patterns
  }

  if (ua.includes("Safari/")) {
    return safari.find(ua); // 155 patterns
  }

  return other.find(ua); // 290 patterns
}

The total above is larger than 431 because some patterns are in both buckets as backstop patterns.

Regular Expression Sanitization

The uap-core regular expression patterns are written for PCRE (Perl Compatible Regular Expressions), which is permissive about unnecessary escape sequences. For example, \! is treated as a literal ! and \- outside a character class is treated as a literal -.

Gleam’s gleam_regexp package compiles regular expressions on JavaScript with the ECMAScript u (Unicode) flag. In Unicode mode, the JavaScript regex engine rejects unrecognized escape sequences as syntax errors rather than silently treating them as literals.

The regular expression compile failures caused by this resulted in 49 of the generated unit tests failing under every JavaScript engine supported by Gleam.

What We Change

The generator (dev/generate_uaparser.gleam) applies a regular expression sanitization function (sanitize_regex) to every pattern before emitting it in the generated code. This function strips unnecessary backslash characters from escape sequences resulting in invalid JavaScript regular expressions in Unicode mode:

• \! → ! (everywhere)
• \- → - (only outside [...] character classes; \- inside a character class is valid and preserved)

Semantic Impact

In PCRE and in JavaScript non-Unicode mode, \! and ! are identical — the backslash is a no-op. The sanitization does not change what any pattern matches. However, the emitted regex strings differ from the upstream uap-core source, so a visual or byte comparison of the generated patterns against regexes.yaml will show differences in these 4 patterns:

Maintenance

If uap-core introduces patterns with other unnecessary escapes, the is_invalid_escape function in the generator must be updated. The full set of characters whose escapes are invalid in JavaScript’s Unicode mode:

! @ # % & = : < > { } ~ ` , ;

The - character is a special case: \- is valid inside [...] but invalid outside.