15.1.2 More Path Utilities

► |  | The Racket Reference

1 | Language Model
2 | Notation for Documentation
3 | Syntactic Forms
4 | Datatypes
5 | Structures
6 | Classes and Objects
7 | Units
8 | Contracts
9 | Pattern Matching
10 | Control Flow
11 | Concurrency and Parallelism
12 | Macros
13 | Input and Output
14 | Reflection and Security
15 | Operating System
16 | Memory Management
17 | Unsafe Operations
18 | Running Racket
| Bibliography
| Index

► | 15 | Operating System

15.1 | Paths
15.2 | Filesystem
15.3 | Networking
15.4 | Processes
15.5 | Logging
15.6 | Time
15.7 | Environment Variables
15.8 | Environment and Runtime Information
15.9 | Command-Line Parsing
15.10 | Additional Operating System Functions

▼ | 15.1 | Paths

15.1.1 | Manipulating Paths
15.1.2 | More Path Utilities
15.1.3 | Unix and Mac OS Paths
15.1.4 | Windows Paths

On this page:

file-name-from-path
path-get-extension
path-has-extension?
filename-extension
find-relative-path
normalize-path
path-element?
path-only
simple-form-path
some-system-path->string
string->some-system-path
shrink-path-wrt

top contents ← prev up next →

##### 15.1.2`` More Path Utilities🔗ℹ

(require racket/path) | package: base

The bindings documented in this section are provided by the racket/path and racket libraries, but not racket/base.

> procedure (file-name-from-path path) → (or/c path-for-some-system? #f)
> path : (or/c path-string? path-for-some-system?)

Returns the last element of path. If path is syntactically a directory path (see split-path), then the result is #f.

> procedure (path-get-extension path) → (or/c bytes? #f)
> path : (or/c path-string? path-for-some-system?)

Returns a byte string that is the extension part of the filename in path, including the . separator. If the path has no extension, #f is returned.

See path-replace-extension for the definition of a filename extension.

Examples:

> > (path-get-extension "x/y.rkt")
> #".rkt"
> > (path-get-extension "x/y")
> #f
> > (path-get-extension "x/y.tar.gz")
> #".gz"
> > (path-get-extension "x/.racketrc")
> #f

Added in version 6.5.0.3 of package base.

> procedure (path-has-extension? path ext) → boolean?
> path : (or/c path-string? path-for-some-system?)
> ext : (or/c bytes? string?)

Determines whether the last element of path ends with ext but is not exactly the same as ext.

If ext is a byte string with the shape of an extension (i.e., starting with . and not including another .), this check is equivalent to checking whether (path-get-extension path) produces ext.

Examples:

> > (path-has-extension? "x/y.rkt" #".rkt")
> #t
> > (path-has-extension? "x/y.ss" #".rkt")
> #f
> > (path-has-extension? "x/y" #".rkt")
> #f
> > (path-has-extension? "x/.racketrc" #".racketrc")
> #f
> > (path-has-extension? "x/compiled/y_rkt.zo" #"_rkt.zo")
> #t

Added in version 6.5.0.3 of package base.

> procedure (filename-extension path) → (or/c bytes? #f)
> path : (or/c path-string? path-for-some-system?)

> NOTE: This function is deprecated; use path-get-extension, instead.

Returns a byte string that is the extension part of the filename in path without the . separator. If path is syntactically a directory (see split-path) or if the path has no extension, #f is returned.

> > procedure
> > (find-relative-path |  | base |
> > |  | path |
> > | [ | #:more-than-root? more-than-root? |
> > |  | #:more-than-same? more-than-same? |
> > |  | #:normalize-case? normalize-case?]) |
> → (or/c path-for-some-system? path-string?)
> base : (or/c path-string? path-for-some-system?)
> path : (or/c path-string? path-for-some-system?)
> more-than-root? : any/c = #f
> more-than-same? : any/c = #t
> normalize-case? : any/c = #t

Finds a relative pathname with respect to base that names the same file or directory as path. Both base and path must be simplified in the sense of simple-form-path. If path shares no subpath in common with base, path is returned.

If more-than-root? is true, if base and path share only a Unix root in common, and if neither base nor path is just a root path, then path is returned.

If path is the same as base, then (build-path 'same) is returned only if more-than-same? is #f. Otherwise, and by default, path is returned when path is the same as base.

If normalize-case? is true (the default), then pairs of path elements to be compared are first converted via normal-case-path, which means that path elements are compared case-insentively on Windows. If normalize-case? is #f, then path elements and the path roots match only if they have the same case.

The result is normally a path in the sense of path?. The result is a string only if path is provided a string and also returned as the result.

Changed in version 6.8.0.3 of package base: Made path elements case-normalized for comparison by default, and added the #:normalize-case? argument.
Changed in version 6.90.0.21: Added the #:more-than-same? argument.

> procedure (normalize-path path [wrt]) → path?
> path : path-string?
> | wrt |  | : |  | (and/c path-string? complete-path?)
> |  |  | = |  | (current-directory)

> > > For most purposes, simple-form-path is the preferred mechanism to normalize a path, because it works for paths that include non-existent directory components, and it avoids unnecessarily expanding soft links.

Returns a complete version of path by making the path complete, expanding the complete path, and resolving all soft links (which requires consulting the filesystem). If path is relative, then wrt is used as the base path.

Letter case is not normalized by normalize-path. For this and other reasons, such as whether the path is syntactically a directory, the result of normalize-path is not suitable for comparisons that determine whether two paths refer to the same file or directory (i.e., the comparison may produce false negatives).

An error is signaled by normalize-path if the input path contains an embedded path for a non-existent directory, or if an infinite cycle of soft links is detected.

Example:

> > (equal? (current-directory) (normalize-path "."))
> #t

> procedure (path-element? path) → boolean?
> path : any/c

Returns #t if path is a path element: a path value for some platform (see path-for-some-system?) such that split-path applied to path would return 'relative as its first result and a path as its second result. Otherwise, the result is #f.

> procedure (path-only path) → (or/c #f path-for-some-system?)
> path : (or/c path-string? path-for-some-system?)

Returns path without its final path element in the case that path is not syntactically a directory; if path has only a single, non-directory path element, #f is returned. If path is syntactically a directory, then path is returned unchanged (but as a path, if it was a string).

Examples:

> > (path-only (build-path "a" "b"))
> #<path:a/>
> > (path-only (build-path "a"))
> #f
> > (path-only (path->directory-path (build-path "a")))
> #<path:a/>
> > (path-only (build-path 'up 'up))
> #<path:../..>

> procedure (simple-form-path path) → path?
> path : path-string?

Returns (simplify-path (path->complete-path path)), which ensures that the result is a complete path containing no up- or same-directory indicators.

> procedure (some-system-path->string path) → string?
> path : path-for-some-system?

Converts path to a string using a UTF-8 encoding of the path’s bytes.

Use this function when working with paths for a different system (whose encoding of pathnames might be unrelated to the current locale’s encoding) and when starting and ending with strings.

> procedure (string->some-system-path str kind) → path-for-some-system?
> str : string?
> kind : (or/c 'unix 'windows)

Converts str to a kind path using a UTF-8 encoding of the path’s bytes.

Use this function when working with paths for a different system (whose encoding of pathnames might be unrelated to the current locale’s encoding) and when starting and ending with strings.

> procedure (shrink-path-wrt pth other-pths) → (or/c #f path?)
> pth : path?
> other-pths : (listof path?)

Returns a suffix of pth that shares nothing in common with the suffixes of other-pths, or pth, if not possible (e.g. when other-pths is empty or contains only paths with the same elements as pth).

Examples:

> > (shrink-path-wrt (build-path "racket" "list.rkt")
> (list (build-path "racket" "list.rkt")
> (build-path "racket" "base.rkt")))
> #<path:list.rkt>
> > (shrink-path-wrt (build-path "racket" "list.rkt")
> (list (build-path "racket" "list.rkt")
> (build-path "racket" "private" "list.rkt")
> (build-path "racket" "base.rkt")))
> #<path:racket/list.rkt>

top contents ← prev up next →