ANTLR4 Grammar
Fileseq v3 uses an ANTLR4 grammar for parsing file sequences. This grammar is shared across Python, Go, and C++ implementations to ensure consistent behavior.
Grammar File
The complete grammar is defined in src/fileseq/grammar/fileseq.g4:
1grammar fileseq;
2
3// ============================================================================
4// Parser Rules
5// ============================================================================
6
7input
8 : sequence EOF
9 | patternOnly EOF
10 | singleFrame EOF
11 | plainFile EOF
12 ;
13
14// Sequence with padding: /path/file.1-100#.exr or /path/file1-100#.exr
15// Also handles hidden files: /path/.hidden5.1-10#.7zip
16// Basename and extension are optional (allows patterns like /path/1-100#.ext)
17// Python-specific: Supports optional subframe patterns:
18// - Dual range: /path/file.1-5#.10-20@@.exr (frameRange with dot prefix + padding)
19// - Composite padding: /path/file.1-5@.#.exr (dot + padding only)
20// Go/C++ ignore the second pair until subframe support is implemented
21sequence
22 : directory basename? frameRange padding (frameRange padding | SPECIAL_CHAR padding)? extension*
23 ;
24
25// Pattern-only sequence (padding without frame range): /path/file.@@.ext
26// Basename and extension are optional (allows patterns like /path/@@@.ext)
27// Python-specific: Supports optional subframe padding: /path/file.#.#.ext
28// Go/C++ ignore the second padding until subframe support is implemented
29patternOnly
30 : directory patBasename? padding (SPECIAL_CHAR padding)? extension*
31 ;
32
33// Single frame: /path/file.100.exr (extension required after frame number)
34// Also handles hidden files: /path/.hidden.100.ext
35// Python semantic rule: a dot-number is only treated as a frame if there's an extension after it
36// Basename is optional to handle cases like .10000000000.123 where both are DOT_NUM tokens
37singleFrame
38 : directory frameBasename? frameNum extension+
39 ;
40
41// Plain file: /path/file.txt or /path/file or /path/.hidden (no frame pattern)
42plainFile
43 : directory plainBasename? extension*
44 ;
45
46// Directory: optional leading slash(es) + segments ending with slash
47// SLASH SLASH? allows one or two leading slashes to support UNC paths (//server/share/)
48directory
49 : (SLASH SLASH?)? (dirSegment SLASH)*
50 ;
51
52// Any token valid in a basename or directory segment.
53// Adding a new lexer token that belongs in basenames only requires updating this rule.
54basenameChar
55 : WORD | NUM | DOT_NUM | DASH | SPECIAL_CHAR | EXTENSION | FRAME_RANGE | DOT_FRAME_RANGE | WS | OTHER_CHAR
56 ;
57
58// Reduced set for plain-file basenames: excludes EXTENSION and DOT_NUM so they
59// are left for the extension rule to consume.
60// HASH and AT are included so that filenames containing literal '#' or '@' characters
61// (e.g. "helloMyPhone#Is911.json") are accepted as plain files rather than rejected.
62// The parser still prefers sequence/patternOnly alternatives (which appear earlier in the
63// input rule) when '#' or '@' appears in a valid padding position.
64plainBasenameChar
65 : WORD | NUM | DASH | SPECIAL_CHAR | FRAME_RANGE | DOT_FRAME_RANGE | WS | OTHER_CHAR | HASH | AT
66 ;
67
68// Directory segments can contain anything including frame-range-like patterns
69// Includes EXTENSION to handle dots in directory names (e.g. path.with.dots)
70// Includes WS to preserve whitespace in directory names
71// Includes OTHER_CHAR for special characters like ! $ % ( ) etc.
72// Includes the padding tokens, since padding only has meaning in the final
73// path component (e.g. /mnt/shot#1/ or /mnt/<UDIM>/ are valid directories)
74dirSegment
75 : (basenameChar | HASH | AT | UDIM_ANGLE | UDIM_PAREN | PRINTF_PAD | HOUDINI_PAD)+
76 ;
77
78// Basename for sequence, patternOnly, and singleFrame rules.
79// Includes EXTENSION (for hidden files like .hidden) and DOT_NUM.
80// Also includes FRAME_RANGE tokens for date-like patterns (e.g., "name_2025-05-13_")
81// The three rules are identical on purpose. Each is referenced from exactly one
82// alternative of 'input', so SLL prediction never merges their follow contexts.
83// Sharing one rule made every range sequence fail SLL and reparse with full LL,
84// which was about 30x slower. TestValidInputsParseWithSLL guards this.
85basename
86 : basenameChar+
87 ;
88
89patBasename
90 : basenameChar+
91 ;
92
93frameBasename
94 : basenameChar+
95 ;
96
97// Basename for plain files: does NOT include EXTENSION or DOT_NUM
98// (so both regular and digit-only extensions can be consumed by extension rule)
99// But DOES include FRAME_RANGE tokens (for filenames like "name_2025-05-13.ext")
100plainBasename
101 : plainBasenameChar+
102 ;
103
104// Frame range: may or may not have leading dot
105// Also includes single frame numbers (for single-frame sequences with padding)
106frameRange
107 : DOT_FRAME_RANGE
108 | FRAME_RANGE
109 | DOT_NUM // Single frame with dot: .100
110 | NUM // Single frame without dot: 100
111 ;
112
113// Single frame number with leading dot: .100 or .-10
114frameNum
115 : DOT_NUM
116 ;
117
118// Padding may use mixed characters (e.g. ###@ = 13 chars with HASH4 style)
119// Each language's PaddingCharsSize handles per-character width calculation
120padding
121 : UDIM_ANGLE
122 | UDIM_PAREN
123 | PRINTF_PAD
124 | HOUDINI_PAD
125 | (HASH | AT)+
126 ;
127
128// Extension can be:
129// - EXTENSION tokens (.tar, .gz, .exr)
130// - DOT_NUM for digit-only extensions (.123, .10000000000)
131// - WORD for non-dot extensions after padding (_exr, _extra)
132// - Followed by optional DASH and NUM (for extensions like .tar.gz-1)
133extension
134 : EXTENSION (DASH NUM)?
135 | DOT_NUM
136 | WORD
137 ;
138
139// ============================================================================
140// Lexer Rules - ORDER MATTERS FOR PRIORITY
141// ============================================================================
142
143// Padding markers - HIGHEST PRIORITY
144// Note: These must come before OTHER_CHAR to match padding first
145UDIM_ANGLE: '<UDIM>';
146UDIM_PAREN: '%(UDIM)d';
147PRINTF_PAD: '%' [0-9]* 'd';
148HOUDINI_PAD: '$F' [0-9]*;
149HASH: '#';
150AT: '@';
151
152// Extension: dot + pattern containing at least one letter
153EXTENSION: '.' ([a-zA-Z_] | [0-9]* [a-zA-Z] [a-zA-Z0-9_]*);
154
155// Frame range with leading dot (must have comma, colon, or dash after first number)
156// Matches: .1-100, .-10-100, .1,2,3, .1-10x2, .1,2,3,5-10,20-30
157// Optional decimal step value, only after x or y: .1-5x0.25
158// Without a step, a trailing .N is a separate frame number (v2 behavior)
159DOT_FRAME_RANGE: '.' '-'? [0-9]+ [,:-] [0-9xy:,-]* ([xy] [0-9]+ '.' [0-9]+)?;
160
161// Frame range without leading dot (must have comma, colon, or dash after first number)
162// Matches: 1-100, -10-100, 1,2,3, 1-10x2
163// Optional decimal step value, only after x or y: 1-5x0.25
164// Without a step, a trailing .N is a separate frame number (v2 behavior)
165FRAME_RANGE: '-'? [0-9]+ [,:-] [0-9xy:,-]* ([xy] [0-9]+ '.' [0-9]+)?;
166
167// Frame number with dot: .100 or .-10 (single frame, no range delimiter)
168DOT_NUM: '.' '-'? [0-9]+;
169
170// Slash separator
171SLASH: '/' | '\\';
172
173// Special characters commonly used in basenames
174SPECIAL_CHAR: [:,.];
175
176// Number sequence (for basenames containing numbers)
177NUM: [0-9]+;
178
179// Words (letters and underscores, no digits or dashes)
180WORD: [a-zA-Z_]+;
181
182// Dash as separate token
183DASH: '-';
184
185// Whitespace as token (don't skip - it's part of filenames)
186WS: [ \t\r\n]+;
187
188// Other valid filename characters (catch-all for POSIX/Windows filenames)
189// Excludes: / \ (path separators), whitespace, and core tokens
190// Includes: ! $ % & ' ( ) + ; = [ ] { } ~ and other printable ASCII
191// Note: $ and % may conflict with padding tokens (HOUDINI_PAD, PRINTF_PAD) in edge cases
192// This is acceptable - such patterns are rare in VFX workflows
193OTHER_CHAR: ~[/\\\r\n\t .,:a-zA-Z0-9_#@<>-]+;
Regenerating the Parser
If you modify the grammar, regenerate the Python parser:
# Using hatch
hatch run generate
# Or directly with Java
java -jar tools/antlr-4.13.1-complete.jar \
-Dlanguage=Python3 \
-visitor \
-o src/fileseq/parser \
src/fileseq/grammar/fileseq.g4
- Requirements:
Java 11+ in PATH
ANTLR 4.13.1 JAR (included in
tools/)
Grammar Rules
The grammar defines four main patterns:
- sequence
Full sequence with frame range and padding:
/path/file.1-100#.exr- patternOnly
Padding without explicit frame range:
/path/file.#.exr- singleFrame
Single frame file:
/path/file.0100.exr- plainFile
No frame pattern:
/path/file.txt
Python-Specific Features
The Python implementation supports additional subframe notation:
Dual range:
file.1-5#.10-20@@.exr(main frames + subframes)Composite padding:
file.1-5@.#.exr(frame + subframe padding)Pattern only:
file.#.#.exr(wildcard for both components)
These patterns are parsed by the grammar but ignored by Go/C++ implementations until subframe support is added.