fnmatch

Port of Python's fnmatch library for Haxe - Unix shell-style wildcards pattern matching
https://github.com/ZaCtalina123/fnmatch

To install, run:

haxelib install fnmatch 1.0.0 

See using Haxelib in Haxelib documentation for more information.

README.md

fnmatch

Port of Python's fnmatch library for Haxe — Unix shell-style wildcard pattern matching.

This library provides filename matching against shell-style patterns using wildcards such as *, ?, [seq], and [!seq], closely mirroring the behavior and API of Python’s standard fnmatch module.

  • Cross-target: works on all Haxe targets (JavaScript, C++, Java, C#, Python, PHP, Lua, HashLink).
  • Python-compatible API: fnmatch, fnmatchcase, filter, translate.
  • Practical differences and platform specifics documented below.

Table of Contents

  • Overview
  • Installation
  • Quick Start
  • API Reference
  • FnMatch.fnmatch
  • FnMatch.fnmatchcase
  • FnMatch.filter
  • FnMatch.translate
  • Behavior and Compatibility
  • Case sensitivity (Windows vs POSIX)
  • Character classes and negation
  • Regex translation differences
  • Escaping rules
  • Examples
  • Testing
  • Performance
  • Limitations
  • Versioning and Release Notes
  • Contributing
  • License
  • Acknowledgements

Overview

This is a Haxe port of Python's fnmatch module. It translates shell-style patterns into regular expressions, caches compiled regular expressions for performance, and exposes a familiar API:

  • fnmatch(name, pattern) — match according to local convention (case-insensitive on Windows).
  • fnmatchcase(name, pattern) — always case-sensitive match.
  • filter(names, pattern) — filter a list of names.
  • translate(pattern) — produce a regex string equivalent to the shell pattern.

The goal is practical compatibility with Python’s behavior, including platform-specific case handling.

Installation

Haxelib (recommended):

haxelib install fnmatch

Git (development version):

haxelib git fnmatch https://github.com/<your-username>/fnmatch.git

Add to your hxml:

-lib fnmatch

Or add to your build step:

haxe -lib fnmatch ...

Quick Start

import fnmatch.FnMatch;

class Main {
  static function main() {
    // Basic matching
    trace(FnMatch.fnmatch("test.txt", "*.txt")); // true

    // Case-sensitive version
    trace(FnMatch.fnmatchcase("Test.TXT", "*.txt")); // false

    // Filter a list of names
    var files = ["a.txt", "b.log", "notes.txt"];
    var txt = FnMatch.filter(files, "*.txt"); // ["a.txt", "notes.txt"]

    // Translate a pattern to a regex string (for EReg)
    var re = FnMatch.translate("file-??.log"); // "^file-..\\.log$"
  }
}

API Reference

Namespace: fnmatch.FnMatch

  • static function fnmatch(name:String, pattern:String):Bool
  • Matches name against pattern using local convention.
  • Case-insensitive on Windows, case-sensitive on POSIX-like targets.
  • Initial dots are not special.
  • Returns true on match, false otherwise.

  • static function fnmatchcase(name:String, pattern:String):Bool

  • Case-sensitive match regardless of platform.
  • Returns true on match, false otherwise.

  • static function filter(names:Array<String>, pattern:String):Array<String>

  • Returns a new array with elements of names that match pattern.
  • Optimized to avoid per-element normalization on POSIX targets.

  • static function translate(pattern:String):String

  • Translates a shell pattern to a Haxe-compatible regex string.
  • Does not compile the regex.
  • Anchored with ^ and $ in this port.

Supported pattern syntax

  • * — matches any sequence of characters (including empty)
  • ? — matches any single character
  • [seq] — matches any character in seq
  • [!seq] — matches any character not in seq

Examples:

  • *.txt, file-??.log, data_[0-9].csv, name[!AEIOU]*

Behavior and Compatibility

Case sensitivity (Windows vs POSIX)

  • fnmatch behavior follows Python:
  • Windows: case-insensitive (both input name and pattern are normalized to lower-case).
  • POSIX: case-sensitive.
  • fnmatchcase is always case-sensitive.

Character classes follow the same rule under fnmatch. On Windows, [a-z] will also match A-Z because case is normalized before matching. Use fnmatchcase for strictly case-sensitive matching.

Character classes and negation

  • [abc] matches any of a, b, c.
  • [a-z] matches any character from a to z (range).
  • [!seq] negates the set; e.g., [!0-9] matches any non-digit.
  • Edge cases:
  • [] is an empty range and never matches.
  • [!] matches only the literal ! (it is not a wildcard).
The implementation escapes set operations &&, `, ~~` in classes to avoid unintended engine-specific semantics.

Regex translation differences

  • Python’s fnmatch.translate returns patterns like (?s:...)\Z and uses atomic groups for backtracking control. Haxe EReg does not support atomic groups or the exact same anchors.
  • This port returns anchored patterns with ^ and $, and uses non-greedy .*? where appropriate to approximate Python’s semantics.
  • For filename matching, these differences should not affect practical results. Newlines are not expected in typical names.

Escaping rules

  • Literal regex metacharacters are escaped when translating non-wildcard characters.
  • Unclosed [ is treated as literal [.

Examples

Match patterns:

FnMatch.fnmatch("report_2024.csv", "report_*.csv"); // true
FnMatch.fnmatch("image001.jpg", "image???.jpg");    // true
FnMatch.fnmatch("Makefile", "*.mk");                // false

Character classes:

FnMatch.fnmatch("a", "[a-c]");      // true
FnMatch.fnmatch("A", "[a-c]");      // Windows: true (fnmatch), POSIX: false (fnmatch)
FnMatch.fnmatchcase("A", "[a-c]");  // false on all platforms
FnMatch.fnmatch("A", "[!a-z]");     // Windows: false (normalized), POSIX: true

Filtering:

var names = ["a.txt", "b.txt", "README.md", "image.png"];
FnMatch.filter(names, "*.txt"); // ["a.txt", "b.txt"]

Translation:

FnMatch.translate("*.txt");    // "^.*\\.txt$"
FnMatch.translate("file[0-9]") // "^file[0-9]$"

Testing

This repository includes tests covering the entire API and edge cases.

Run tests with the interpreter:

haxe -cp src -cp test -main TestRunner --interp

Run tests for specific targets:

# JavaScript
haxe -cp src -cp test -main TestRunner -js bin/test.js && node bin/test.js

# C++
haxe -cp src -cp test -main TestRunner -cpp bin && ./bin/TestRunner

# Java
haxe -cp src -cp test -main TestRunner -java bin && java -jar bin/TestRunner.jar

Performance

  • The port caches compiled regexes similarly to Python’s lru_cache. In this implementation, a simple map with a maximum size is used; when the capacity is reached, the cache is reset. This provides predictable memory usage with good performance for common usage patterns.
  • Consecutive * characters are coalesced into a single * during translation.

Limitations

  • Regex engine differences: Haxe EReg does not support atomic groups or Python’s exact anchors. The translation uses ^...$ and non-greedy quantifiers to approximate Python behavior.
  • Newlines: The dot . may not match newlines depending on the target; filenames are not expected to contain newlines.
  • This library does not interpret path separators specially; it operates purely on strings, matching Python’s fnmatch semantics.

Versioning and Release Notes

This project follows semantic versioning.

  • 1.0.0
  • Initial release.
  • API parity with Python fnmatch: fnmatch, fnmatchcase, filter, translate.
  • Cross-target tests and platform-specific behavior aligned with Python.

Contributing

Contributions are welcome:

  • File issues for bugs or inconsistencies with Python behavior.
  • Open pull requests with tests for new features or fixes.
  • Keep code comments and public docs in English.

License

MIT License. See the LICENSE file for details.

Acknowledgements

This project is based on Python’s fnmatch module from the Python Standard Library and aims to provide practical compatibility within the constraints of Haxe’s cross-platform regex capabilities.

Contributors
ZaCtalina123
Version
1.0.0
Published
1 year ago
License
MIT

All libraries are free

Every month, more than a thousand developers use Haxelib to find, share, and reuse code — and assemble it in powerful new ways. Enjoy Haxe; It is great!

Explore Haxe

Haxe Manual

Haxe Code Cookbook

Haxe API documentation

You can try Haxe in the browser! try.haxe.org

Join us on GitHub!

Haxe is being developed on GitHub. Feel free to contribute or report issues to our projects.

Haxe on GitHub

⌂