6.44.1 String and bytevector pathnames handling

All the file–related functions defined by R6RS accept a Scheme string as representing a file pathname; internally such string is converted to a bytevector to be handed to the underlying operating system.

The following bindings are exported by the library (vicare).

Parameter: string->filename-func

Parameter: string->pathname-func

In Vicare the string–to–filename conversion is performed by the function returned by string->filename-func, which defaults to string->utf8.

Parameter: filename->string-func

Parameter: pathname->string-func

In Vicare the filename–to–string conversion is performed by the function returned by filename->string-func, which defaults to utf8->string.

Function: directory-exists? ptn

Return #t if ptn is a string or bytevector representing the pathname of an existent directory; otherwise return #f.

The following bindings are exported by the library (vicare language-extensions posix).

Function: file-pathname? obj

Function: file-string-pathname? obj

Function: file-bytevector-pathname? obj

Return #t if obj is a string or bytevector, not empty, not including a character whose ASCII representation is the null byte.

Function: file-absolute-pathname? pathname

Function: file-string-absolute-pathname? pathname

Function: file-bytevector-absolute-pathname? pathname

The argument pathname must be a string or bytevector. Return #t if pathname starts with a / character, which means it is valid as Unix–style absolute pathname; otherwise return #f.

This function only acts upon its argument, never accessing the file system.

Function: file-relative-pathname? pathname

Function: file-string-relative-pathname? pathname

Function: file-bytevector-relative-pathname? pathname

The argument pathname must be a string or bytevector. Return #t if pathname doest not start with a / character, which means it is valid as Unix–style relative pathname; otherwise return #f.

This function only acts upon its argument, never accessing the file system.

Function: split-pathname-root-and-tail pathname

Given a string representing a pathname: split it into the directory part and the tail part. Return 2 values: a string representing the directory part and a string representing the tail name part. If pathname is just the name of a file or directory relative to the current directory: the directory part is empty and the first returned value is the empty string.

Assume the pathname components separator is /, which is Unix–specific.

(receive (root tail)
    (split-pathname-root-and-tail "a/b")
  (list root tail))
⇒ ("a" "b")

(receive (root tail)
    (split-pathname-root-and-tail "ciao")
  (list root tail))
⇒ ("" "ciao")

Function: file-colon-search-path? obj

Function: file-string-colon-search-path? obj

Function: file-bytevector-colon-search-path? obj

Return #t if obj is a string or bytevector, possibly empty, not including a character whose ASCII representation is the null byte.

Function: split-search-path path

Function: split-search-path-bytevector bytevector-path

Function: split-search-path-string string-path

Split a file search path into its components and return a list of pathnames. A search path is meant to be a list of directory pathnames separated by a colon character; bytevector-path must be a bytevector, string-path must be a Scheme string, path must be a Scheme string or bytevector. Empty pathnames are discarded.

#!vicare
(import (vicare))

(split-search-path-bytevector '#vu8())
⇒ ()

(split-search-path-bytevector #ve(ascii "ciao:hello"))
⇒ (#ve(ascii "ciao") #ve(ascii "hello"))

(split-search-path-bytevector '#ve(ascii "::::"))
⇒ ()

(split-search-path-string "")
⇒ ()

(split-search-path-string "ciao:hello:salut")
⇒ ("ciao" "hello" "salut")

(split-search-path-string "::::")
⇒ ()

(split-search-path "ciao:hello:salut")
⇒ ("ciao" "hello" "salut")

(split-search-path '#ve(ascii "ciao:hello:salut"))
⇒ (#ve(ascii "ciao") #ve(ascii "hello") #ve(ascii "salut"))

Function: list-of-pathnames? obj

Function: list-of-string-pathnames? obj

Function: list-of-bytevector-pathnames? obj

Return #t if obj is a proper list of pathnames according to file-pathname?, file-string-pathname?, file-bytevector-pathname?.

Function: split-pathname pathname

Function: split-pathname-bytevector bytevector-pathname

Function: split-pathname-string string-pathname

Split a file pathname into its components and return two values: a boolean, true if the pathname starts with a slash characters; the list of components which can be empty.

A pathname is meant to be a file or directory name with components separated by a slash character; bytevector-pathname must be a bytevector, string-pathname must be a Scheme string, path must be a Scheme string or bytevector.

Empty components are discarded.

#!vicare
(import (vicare))

(split-pathname-bytevector '#vu8())
error→ "invalid pathname"

(split-pathname-bytevector '#ve(ascii "ciao/hello"))
⇒ #f (#ve(ascii "ciao") #ve(ascii "hello"))

(split-pathname-bytevector '#ve(ascii "////"))
⇒ #t ()

(split-pathname-string "")
error→ "invalid pathname"

(split-pathname-string "ciao/hello/salut")
⇒ #f ("ciao" "hello" "salut")

(split-pathname-string "////")
⇒ #t ()

(split-pathname "ciao/hello/salut")
⇒ #f ("ciao" "hello" "salut")

(split-pathname '#ve(ascii "/ciao/hello/salut"))
⇒ #t (#ve(ascii "ciao") #ve(ascii "hello") #ve(ascii "salut"))

Function: search-file-in-environment-path pathname environment-variable

Search a file pathname (regular file or directory) in the given search path.

pathname must be a string representing a file pathname; environment-variable must be a string representing a system environment variable.

• If pathname is absolute, test its existence: when found, return a string representing the real absolute file pathname; otherwise return #f.
• If pathname is relative and it has a directory part, test its existence: when found, return a string representing the real absolute file pathname; otherwise return #f.
• If pathname is relative and it has no directory part, read the environment variable as colon–separated list of directories and search the file in them, from the first to the last: when found, return a string representing the real absolute file pathname; otherwise return #f.

  Notice that the file is searched in the process’ current working directory only if such directory is listed in the given path.

Function: search-file-in-list-path pathname list-of-directories

Search a file pathname (regular file or directory) in the given search path.

pathname must be a string representing a file pathname; list-of-directories must be a list of strings representing directory pathnames.

• If pathname is absolute, test its existence: when found, return a string representing the real absolute file pathname; otherwise return #f.
• If pathname is relative and it has a directory part, test its existence: when found, return a string representing the real absolute file pathname; otherwise return #f.
• If pathname is relative and it has no directory part, search the file in the given directories, from the first to the last: when found, return a string representing the real absolute file pathname; otherwise return #f.

  Notice that the file is searched in the process’ current working directory only if such directory is listed in the given path.