▼File:   Racket File and Format Libraries
On this page:
glob/  c
glob
in-glob
glob-match?
glob-quote
glob-capture-dotfiles?
  top  contents    up   

15 Globbing

 (require file/glob) package: base

The file/glob library implements globbing for path-string? values. A glob is a path string that matches a set of path strings using the following wildcards:

  • A sextile (*) matches any sequence of characters in a file or directory name.

  • Two sextiles (**) match any sequence of characters and any number of path separators.

  • A question mark (?) matches any single character in a file or directory name.

  • Square bracket-delimited character groups, e.g. [abc], match any character within the group. The square brackets have the same meaning in globs as in regular expressions, see Regexp Syntax.

  • If the glob ends with a path separator (/ on any (system-type), additionally \ on 'windows) then it only matches directories.

On Windows, wildcards cannot be escaped because \ is a path separator.

By default, wildcards will not match files or directories whose name begins with a period (aka "dotfiles"). To override, set the parameter glob-capture-dotfiles? to a non-#f value or supply a similar value using the #:capture-dotfiles? keyword.

value

glob/c : (or/c path-string? (sequence/c path-string?))

A flat contract that accepts a glob or a sequence of globs.

All file/glob functions accept glob/c values. These functions also recognize braces ({}) as a meta-wildcard for describing multiple globs.

Braces are interpreted before any other wildcards.

procedure

(glob pattern 
  [#:capture-dotfiles? capture-dotfiles?]) 
 → (listof path-string?)
  pattern : glob/c
  capture-dotfiles? : boolean? = (glob-capture-dotfiles?)
Builds a list of all paths on the current filesystem that match any glob in pattern. The order of paths in the result is unspecified.

If pattern contains the wildcard **, then glob recursively searches the filesystem to find matches. For example, the glob "/**.rkt" will search the entire filesystem for files or directories with a ".rkt" suffix (aka, Racket files).

Examples:
> (glob "*.rkt")
;; Lists all Racket files in current directory
 
> (glob "*/*.rkt")
;; Lists all Racket files in all sub-directories of the current directory.
;; (Does not search sub-sub-directories, etc.)
 
> (glob (build-path (find-system-path 'home-dir) "**" "*.rkt"))
;; Recursively searches home directory for Racket files, lists all matches.
 
> (glob "??.rkt")
;; Lists all Racket files in current directory with 2-character names.
 
> (glob "[a-z0-9].rkt")
;; Lists all Racket files in current directory with single-character,
;; alphanumeric names.
 
> (glob '("foo-bar.rkt" "foo-baz.rkt" "qux-bar.rkt" "qux-baz.rkt"))
;; Filters the list to contain only files or directories that exist.
 
> (glob "{foo,qux}-{bar,baz}.rkt")
;; Same as above, returns at most 4 files.

procedure

(in-glob pattern 
  [#:capture-dotfiles? capture-dotfiles?]) 
 → (sequence/c path-string?)
  pattern : glob/c
  capture-dotfiles? : boolean? = (glob-capture-dotfiles?)
Returns a stream of all paths matching the glob pattern, instead of eagerly building a list.

procedure

(glob-match? pattern    
  path    
  [#:capture-dotfiles? capture-dotfiles?]) → boolean?
  pattern : glob/c
  path : path-string?
  capture-dotfiles? : boolean? = (glob-capture-dotfiles?)
Analogous to regexp-match?; returns #true if path matches any glob in pattern.

(glob-match? pattern path) is not the same as:

(member path (glob pattern))

because glob only returns files/directories that exist, whereas glob-match? does not check that path exists.

This operation accesses the filesystem.

procedure

(glob-quote str) → string?

  str : string?
(glob-quote path) → path?
  path : path?
Escapes all glob wildcards and glob meta-wildcards in the given string or path string.

Examples:
> (glob-quote "*.rkt")

"\\*.rkt"

> (glob-quote "[Ff]ile?{zip,tar.gz}")

"\\[Ff\\]ile\\?\\{zip\\,tar.gz\\}"

> (glob-quote "]")

"\\]"

parameter

(glob-capture-dotfiles?) → boolean?

(glob-capture-dotfiles? capture-dotfiles?) → void?
  capture-dotfiles? : boolean?
 = #f
Determines whether wildcards match names that begin with a #\. character. If #t, the wildcards will match dotfiles. If #f, use a glob such as ".*" to match dotfiles explicitly.

  top  contents    up