bmx-site/docs/api/brl/brl_path.md

---

id: brl.path title: BRL.Path

sidebar_label: Introduction

BRL.Path provides an object-oriented, cross-platform way to represent and work with file system paths.

At its core is the TPath type, which wraps a normalized path string and provides convenient operations for:

• Joining and transforming paths (including the / operator).
• Resolving and relativizing paths ( Resolve and Relativize).
• Querying the filesystem ( Exists, IsFile, IsDir, Size, timestamps, etc).
• Creating, deleting, renaming and copying files/directories.
• Iterating directory contents ( IterDir / List).
• Globbing and pattern matching ( Glob, GlobIter, MatchGlob).
• Walking a directory tree ( Walk).

The module is designed to behave consistently whether using the native filesystem or the virtual filesystem when BRL.Io / MaxIO is enabled.

Quick start

SuperStrict

Framework brl.standardio
Import BRL.Path

Local p:TPath = New TPath("src") / "core" / "main.bmx"

Print p.ToString()   ' src/core/main.bmx
Print p.Name()       ' main.bmx
Print p.BaseName()   ' main
Print p.Extension()  ' bmx
Print p.Parent().ToString() ' src/core

Path normalization

When a TPath is created, the path is normalized:

• Backslashes are converted to forward slashes (\ → /).
• Trailing slashes are removed (except for a root path such as /).

This keeps equality comparisons stable and predictable.

Joining paths

Use Join, Child, or the / operator:

Local root:TPath = New TPath("/etc")
Local q:TPath = root / "init.d" / "reboot"

Print q.ToString() ' /etc/init.d/reboot

If the right-hand side is a rooted path, it replaces the left-hand side:

Local a:TPath = New TPath("a/b")
Local b:TPath = a / "/x/y"
Print b.ToString() ' /x/y

Resolve and Relativize

Resolve appends a relative path (or replaces the base if the argument is rooted):

Local base:TPath = New TPath("/a/b")
Local resolved:TPath = base.Resolve("c/d")
Print resolved.ToString() ' /a/b/c/d

Relativize constructs a relative path from one path to another:

Local p:TPath = New TPath("/a/b")
Local q:TPath = New TPath("/a/b/c/d")
Local r:TPath = p.Relativize(q)

Print r.ToString() ' c/d

Relativization is the inverse of resolution. For normalized paths p and relative q:

p.Relativize(p.Resolve(q)).Equals(q)

A relative path cannot be constructed if only one of the paths is rooted, or if rooted paths have different root components.

Querying the filesystem

TPath exposes filesystem queries through simple methods:

• Exists
• FileType, IsFile, IsDir
• Size
• ModifiedTime / ModifiedDateTime

• CreatedTime / CreatedDateTime

  Local p:TPath = New TPath("README.md")
  If p.Exists() Then
  	Print "Size: " + p.Size()
  	Print "Modified: " + p.ModifiedDateTime().ToString()
  End If
  

Creating, deleting, renaming and copying

Local dir:TPath = New TPath("build")
dir.CreateDir(True)

Local file:TPath = dir / "out.txt"
file.CreateFile()

file.CopyFileTo(dir / "out_copy.txt")

Local moved:TPath
If file.RenameTo(dir / "moved.txt", moved) Then
	Print "Moved to: " + moved.ToString()
End If

Directory listing

Use IterDir to iterate lazily, or List to build an array.

The iterator holds an open directory handle while iterating; if you exit early, close it (or use a Using block).

Using
	Local it:TPathDirIterator = New TPath("src").IterDir()
Do
	For Local p:TPath = EachIn it
		Print p.Name()
	Next
End Using

Globbing

Glob and GlobIter expand glob patterns to matching filesystem entries.

Supported pattern features include:

• * matches zero or more characters within a segment.
• ? matches a single character within a segment.
• Character classes: [abc], [a-z], and negated [!abc] / [^abc].
• Backslash escaping (unless EGlobOptions.NoEscape is set).
• Brace expansion {a,b} (textual expansion before globbing).
• ** globstar recursion when EGlobOptions.GlobStar is enabled.

By default, wildcard patterns do not match entries whose names begin with .. Enable EGlobOptions.Period to include dotfiles.

Iterating results (recommended)

Using
	Local it:TPathIterator = New TPath("src").GlobIter("**/*.bmx", EGlobOptions.GlobStar)
Do
	For Local p:TPath = EachIn it
		Print p.ToString()
	Next
End Using

Including files in the starting directory

A pattern of the form **/pattern matches only files below the starting directory (because the / is required).

To include files in the starting directory as well, combine patterns using brace expansion:

Local p:TPath = New TPath("examples")

Using
	Local it:TPathIterator = p.GlobIter("{*.bmx,**/*.bmx}", EGlobOptions.GlobStar)
Do
	For Local f:TPath = EachIn it
		Print f.Name()
	Next
End Using

Matching without filesystem access

MatchGlob matches a path against a pattern without touching the filesystem.

This is useful for filtering paths produced by other traversal methods:

Local p:TPath = New TPath("/path/to/sub/file.txt")
If p.MatchGlob("sub/*.txt") Then
	Print "Matched!"
End If

Walking a file tree

Walk traverses a directory tree and calls an IPathWalker for each entry.

Type TPrintWalker Implements IPathWalker
	Method WalkPath:EFileWalkResult(attributes:SPathAttributes Var)
		Print attributes.GetPath().ToString()
		Return EFileWalkResult.OK
	End Method
End Type

New TPath(".").Walk(New TPrintWalker)

Traversal can be configured using EFileWalkOption (for example, following symlinks) and the maxDepth parameter.

Resource management and Using

Iterators returned by IterDir and GlobIter may hold native resources (directory handles). If the iterator is not fully consumed, close it explicitly, or prefer a Using block:

Using
	Local it:TPathIterator = New TPath("src").GlobIter("**/*.bmx", EGlobOptions.GlobStar)
Do
	For Local p:TPath = EachIn it
		Print p.Name()
		Exit ' stop early, resources are still released at End Using
	Next
End Using

Provides the TPath class for representing and manipulating filesystem paths,

Types

Type	Description
TPath	Class representing and manipulating file system paths.
TPathDirIterator	Iterator over the direct children of a directory TPath.

Interfaces

Interface	Description
IPathWalker	Interface for receiving callbacks during a file tree walk.

Structs

Struct	Description
SPathAttributes	Structure representing file or directory attributes.