filepath
Path functions that never touch the file system; the same work as the fs.path package.
import filepath
The filepath package takes path strings apart and builds them: Join, Dir, Base, Ext, Stem, Clean, Abs, Rel and the IsSafe check for paths that come from users. It works on strings alone and never touches the file system, apart from Abs, Rel and IsSafe, which read the current directory for a relative path. Use it in build tools, static site generators, upload handlers and anywhere a path is computed rather than typed. To act on the files themselves, pair it with fs, fs.dir or os.
The fs.path package is a set of other names for the same functions; use whichever reads better to you, but one per program. The names differ a little: Base here is Filename there, and Dir is Dirname. Watch out for path.Basename, which is Stem and drops the extension, unlike Base. Paths always come out with / as the separator, on Windows too, and Windows accepts that.
What people get wrong:
- Expecting
Jointo clean the result. It only places one/between the parts:Join("a/b", "../c")isa/b/../c, and an absolute second part is appended, not substituted. CallCleanafterwards. - Comparing paths as plain text. Clean both first, and remember that the comparison is case sensitive.
- Trusting a user's path without
IsSafe. Even afterJoin,../../etc/passwdclimbs out of your folder.
Windows paths
A path pasted by a Windows user, or read from a Windows config file, uses \. Every function here calls Normalize first, so Dir, Base and Join accept both kinds. IsAbs also treats a drive letter such as C:/ as absolute.
import filepath
func main:
raw := "C:\\Users\\Sara\\Documents\\cv.pdf"
p := filepath.Normalize(raw)
println p
println filepath.IsAbs(p), filepath.IsAbs("Documents\\cv.pdf")
println filepath.Dir(p)
println filepath.Base(p), filepath.Stem(p), filepath.Ext(p)
println filepath.Join("C:\\Users\\Sara", "Pictures\\cat.jpg")
println filepath.Clean("D:/games/../music/./song.mp3")
endIn a Salam string a single backslash is written \\. Clean treats the drive as an ordinary first part, so C:/../x becomes x; do not climb above the drive with ...
Edge cases worth knowing
The table below runs Dir, Base, Ext and Clean over inputs that often cause bugs: the root, an empty string, a trailing slash, a dot file and a double extension.
import filepath
import fmt
func show(p: str):
print fmt.PadRight("[" + p + "]", 20)
print fmt.PadRight(filepath.Dir(p), 10)
print fmt.PadRight(filepath.Base(p), 16)
print fmt.PadRight("[" + filepath.Ext(p) + "]", 8)
println filepath.Clean(p)
end
func main:
println "path dir base ext clean"
each p in ["/", "", "docs/", "/var/log/app.log", ".bashrc", "backup.tar.gz", "../up/x.txt", "a/./b/../c.txt"]:
show(p)
end
endThe rules it shows: a trailing slash is ignored; an empty path counts as .; a name that starts with a dot, like .bashrc, has no extension; Ext returns only the last extension, so test for .tar.gz with str.EndsWith when you need it. Dir does not simplify, so call Clean first when the path may contain . or ...
Grouping files by extension
Ext with a HashMap counts files by type, for a report or to pick a handler for each file. A second vector remembers the order in which the extensions first appeared, so the output does not depend on the map's internal order.
import filepath
func main:
files := ["src/main.salam", "src/util.salam", "README.md", "docs/guide.md", "logo.svg", "Makefile", "docs/intro.md"]
order := Vector {} as Vector<str>
defer order.Free()
counts := HashMap {} as HashMap<str, int>
each f in files:
mut ext := filepath.Ext(f)
if ext.Len() == 0: ext = "(none)" end
if counts.Has(ext):
counts.Put(ext, counts.Get(ext) + 1)
else:
counts.Put(ext, 1)
order.Push(ext)
end
end
each ext in order:
println ext, counts.Get(ext)
end
endExt keeps the case of the name, so photo.JPG gives .JPG. Pass it through str.Lower before comparing when the files come from a camera or from Windows.
Constants and variables
Separator
const Separator: str = "/"/, on Windows too.import filepath
func main:
p := filepath.Join("projects", "salam/main.salam")
println p, filepath.Separator
println filepath.Dir(p), filepath.Base(p), filepath.Ext(p), filepath.Stem(p)
println filepath.Normalize("a//b/./c/"), filepath.Clean("a/b/../c")
println filepath.IsAbs("/usr/bin"), filepath.IsAbs(p), filepath.IsAbs(filepath.Abs(p))
println filepath.Rel("/a/b", "/a/b/c/d")
println filepath.IsSafe("/srv", "x/y"), filepath.IsSafe("/srv", "../etc")
println filepath.Validate("a/b")
endFunctions
Match
func Match(pattern: str, name: str): boolname matches the glob pattern: * any run of characters except /, ? one character, [a-c] a set or range, [!a-c] its opposite, \ to take the next character literally, and ** any run including / (**/ also matches no folder at all, so **/*.c matches x.c). The whole name must match. A pattern with an unclosed [ matches nothing, and a \ at the very end matches a backslash. A range such as [a-c] compares whole characters, so it works for Persian letters too.import filepath
func check(pattern: str, name: str):
println pattern, name, filepath.Match(pattern, name)
end
func main:
check("*.salam", "main.salam")
check("*.salam", "std/main.salam")
check("**/*.salam", "std/os/main.salam")
check("**/*.salam", "main.salam")
check("v?.[0-9]", "v1.5")
check("[!a-c]*", "dog")
check("cache/**", "cache/a/b")
println filepath.HasMeta("src/main.salam"), filepath.HasMeta("src/*.salam")
endHasMeta
func HasMeta(pattern: str): bool*, ?, [ or \), that is, when it is not just a plain path.The example for this item is shown with the ones above: filepath-Match.salam
Normalize
func Normalize(p: str): str\ separators into / and changes nothing else; see Clean for . and ...The example for this item is shown with the ones above: filepath-Join.salam
IsAbs
func IsAbs(p: str): boolC:/ counts as absolute.The example for this item is shown with the ones above: filepath-Join.salam
Join
func Join(a: str, b: str): str/ between them. An empty part gives the other one. It does not resolve .. and does not let an absolute second part replace the first.The example for this item is shown with the ones above: filepath-Join.salam
Base
func Base(p: str): str/ stays / and an empty path gives ..The example for this item is shown with the ones above: filepath-Join.salam
Dir
func Dir(p: str): str. when there is no folder and / at the root. It does not simplify ...The example for this item is shown with the ones above: filepath-Join.salam
Ext
func Ext(p: str): str.bashrc.The example for this item is shown with the ones above: filepath-Join.salam
Stem
func Stem(p: str): strThe example for this item is shown with the ones above: filepath-Join.salam
Clean
func Clean(p: str): str. and .., removes repeated and trailing slashes, and gives . for an empty path. A drive letter is treated as an ordinary first part.The example for this item is shown with the ones above: filepath-Join.salam
Abs
func Abs(p: str): strThe example for this item is shown with the ones above: filepath-Join.salam
Rel
func Rel(base: str, target: str): strbase to target, using .. when the target lies outside; both are made absolute first.The example for this item is shown with the ones above: filepath-Join.salam
Validate
func Validate(p: str): boolThe example for this item is shown with the ones above: filepath-Join.salam
IsSafe
func IsSafe(base: str, p: str): boolp, joined to base and cleaned, is base or lies inside it; an empty p is refused. Text only, so symbolic links are not followed.The example for this item is shown with the ones above: filepath-Join.salam