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
nameagainstpatternusing local convention. - Case-insensitive on Windows, case-sensitive on POSIX-like targets.
- Initial dots are not special.
-
Returns
trueon match,falseotherwise. -
static function
fnmatchcase(name:String, pattern:String):Bool - Case-sensitive match regardless of platform.
-
Returns
trueon match,falseotherwise. -
static function
filter(names:Array<String>, pattern:String):Array<String> - Returns a new array with elements of
namesthat matchpattern. -
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 inseq[!seq]— matches any character not inseq
Examples:
*.txt,file-??.log,data_[0-9].csv,name[!AEIOU]*
Behavior and Compatibility
Case sensitivity (Windows vs POSIX)
fnmatchbehavior follows Python:- Windows: case-insensitive (both input name and pattern are normalized to lower-case).
- POSIX: case-sensitive.
fnmatchcaseis 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 ofa,b,c.[a-z]matches any character fromatoz(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.translatereturns patterns like(?s:...)\Zand 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
fnmatchsemantics.
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.