Standard library · System and tools

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 Join to clean the result. It only places one / between the parts: Join("a/b", "../c") is a/b/../c, and an absolute second part is appended, not substituted. Call Clean afterwards.
  • Comparing paths as plain text. Clean both first, and remember that the comparison is case sensitive.
  • Trusting a user's path without IsSafe. Even after Join, ../../etc/passwd climbs 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.

filepath-guide-windows.salam
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")
end
OutputC:/Users/Sara/Documents/cv.pdf true false C:/Users/Sara/Documents cv.pdf cv .pdf C:/Users/Sara/Pictures/cat.jpg D:/music/song.mp3

In 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.

filepath-guide-edges.salam
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
end
Outputpath dir base ext clean [/] / / [] / [] . . [] . [docs/] . docs [] docs [/var/log/app.log] /var/log app.log [.log] /var/log/app.log [.bashrc] . .bashrc [] .bashrc [backup.tar.gz] . backup.tar.gz [.gz] backup.tar.gz [../up/x.txt] ../up x.txt [.txt] ../up/x.txt [a/./b/../c.txt] a/./b/.. c.txt [.txt] a/c.txt

The 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.

filepath-guide-group.salam
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
end
Output.salam 2 .md 3 .svg 1 (none) 1

Ext 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 = "/"
The separator between the parts of a path: always /, on Windows too.
filepath-Join.salam
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")
end
Outputprojects/salam/main.salam / projects/salam main.salam .salam main a//b/./c/ a/c true false true c/d true false true

Functions

Match

func Match(pattern: str, name: str): bool
Reports whether name 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.
filepath-Match.salam
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")
end
Output*.salam main.salam true *.salam std/main.salam false **/*.salam std/os/main.salam true **/*.salam main.salam true v?.[0-9] v1.5 true [!a-c]* dog true cache/** cache/a/b true false true

HasMeta

func HasMeta(pattern: str): bool
True when the pattern contains a glob character (*, ?, [ 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
Turns \ 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): bool
True when the path is absolute; a Windows path such as C:/ 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
Joins two parts of a path with exactly one / 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
The last part of a path, extension included; a trailing slash is ignored, / 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
The path without its last part: . 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
The last extension, with its dot, in its original case; empty for a name without one and for a dot file such as .bashrc.

The example for this item is shown with the ones above: filepath-Join.salam

Stem

func Stem(p: str): str
The last part's name without its last extension.

The example for this item is shown with the ones above: filepath-Join.salam

Clean

func Clean(p: str): str
Simplifies a path: resolves . 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): str
Makes a path absolute against the current directory and cleans it; an absolute path is only cleaned.

The example for this item is shown with the ones above: filepath-Join.salam

Rel

func Rel(base: str, target: str): str
The relative path from base 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): bool
True when the path is not empty. It is not a safety check.

The example for this item is shown with the ones above: filepath-Join.salam

IsSafe

func IsSafe(base: str, p: str): bool
True when p, 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