The ppath Reference Manual

This is the ppath Reference Manual, version 0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sat Dec 03 22:55:59 2022 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 ppath

A Common Lisp path handling library based on Python’s os.path module

Author

Alexey Veretennikov

License

BSD

Long Description

[![Build Status](https://travis-ci.org/fourier/ppath.svg?branch=master)](https://travis-ci.org/fourier/ppath)
# A Common Lisp path strings manipulation library.

This library is a path strings manipulation library inspired by Python’s **os.path**. All functionality from **os.path** is supported on major operation systems (OSX, Linux, Windows).

The philosophy behind is to use simple strings and "dumb" string manipulation functions to handle paths and filenames. Where possible the corresponding OS system functions are called.

Supported [tested] compilers: LispWorks (6.1PE and 7.0), CCL, SBCL.
Tested on the following platforms:

#### Windows
- Clozure CL Version 1.11-r16635 (WindowsX8664)
- LispWorks 6.1.1 Personal Edition 32bit
- LispWorks 7.0 Hobbyist Edition 32bit
- SBCL 1.3.15

Limitations: On Win32 assumed OS versions with Unicode support.

#### Linux
- SBCL 1.3.14
- CCL 1.11.5

#### OSX
- Lispworks 7.0 Hobbyist DV Edition 32bit
- Clozure CL Version 1.11

## Usage
The library consist of 3 packages: *ppath*, *ppath-nt* and *ppath-posix*. The generic package *ppath* forwards calls to appropriate OS-dependent library. It exports only functions available for the current platform.

## Semantical difference from Python’s os.path module
- Where possible do not raise an error, but rather return “‘nil“‘.
- “‘samestat“‘ function is not implemented (makes no sense since osicat’s wrapper around stat()/fstat() calls is used)
- “‘walk“‘ is not implemented (there is already a couple of good implementations around)

## API description

### *function* ppath:abspath (“‘path“‘)
Convert relative “‘path“‘ to absolute.
If path is absolute return it unchanged.
If path is empty return current directory.

On POSIX systems invariant:
“‘(abspath path) == (normpath (join (getcwd) path))“‘



### *function* ppath:basename (“‘path“‘)
Extract the base name (filename) of the “‘path“‘.

Example:
On Windows:
“‘lisp
CL-USER > (basename "C:\\dir\\file.txt")
=> file.txt
“‘

On POSIX:
“‘lisp
CL-USER > (basename "/foo/bar")
=> bar
“‘

Invariant:
“‘(basename path) == (cdr (split path))“‘


### *function* ppath:commonprefix (“‘&rest paths“‘)
Get the common prefix substring of all strings in “‘paths“‘. The separators are not translated, so paths interpreted just as normal strings.

“‘paths“‘ components could also be lists of strings, like results of “‘split“‘ operation on paths. In this case the comparison happens elementwise.

Example:

“‘lisp
CL-USER > (commonprefix ’("/home/username/dir" "/home/user/test"))
=> /home/user
“‘

### *function* ppath:dirname (“‘path“‘)
Get the directory name of the “‘path“‘.

Example:

“‘lisp
CL-USER > (dirname "/foo/bar")
=> /foo
“‘

Example (Windows):

“‘lisp
CL-USER > (dirname "C:\\dir\\file.txt")
=> C:\\dir
“‘
Invariant: “‘(dirname path) == (car (split path))“‘

### *function* ppath:exists (“‘path“‘)
Check if the “‘path“‘ is an existing path.
On POSIX returns “‘nil“‘ for broken symbolic links.


### *function* ppath:expanduser (“‘PATH“‘)
Expand ~ and ~user in the “‘path“‘ with the contents of user’s home path.

* ~ - home directory
* ~user - user’s home directory

Return “‘path“‘ unchanged if unable to expand.

On Windows the path is taken either from **HOME** or **USERPROFILE**, or constructed via **HOMEPATH** and **HOMEDRIVE**.
On error just return original “‘path“‘ value.
On POSIX systems the ~ is replaced with contents of the **HOME** environment variable or taken from password database (“‘/etc/passwd“‘ or similar).

Examples (POSIX): (given the user "username" with home directory /Users/username)

“‘lisp
CL-USER > (expanduser "~/dir")
=> /Users/username/dir
CL-USER > (expanduser "~root/dir")
=> /root/dir
“‘

Windows: if **HOMEPATH** is "users\dir" and **HOMEDRIVE** is "C:\\",

“‘lisp
CL-USER > (expanduser "~test")
=> C:\users\test
“‘

### *function* ppath:expandvars (“‘path &optional (modify-in-quotes t)“‘)

Expand the “‘path“‘ replacing environment variables with their contents.

The variables like “‘${var}“‘ and “‘$var“‘ (and additionally “‘%var%“‘ on Windows) are getting replaced by their values.

All unknown or malformed variables ignored and kept as it is.

The difference between Windows and POSIX systems is that on Windows variables inside single quotes are not expanded, i.e. "“‘’$HOME’“‘" will remain "“‘’$HOME’“‘", while on POSIX systems it will be expanded. The optional argument “‘modify-in-quotes“‘ allows to change this behavior.
This behavior kept for compatibility with Python’s “‘os.path.expandvars“‘.

Example:
“‘lisp
CL-USER > (expandvars "$HOME/.bashrc")
=> /home/username/.bashrc
CL-USER > (osicat-posix:setenv "foo" "abcd")
=> 0
CL-USER > (expandvars "’$foo’$bar" nil)
=> ’$foo’$bar
CL-USER > (expandvars "’$foo’$bar" t)
=> ’abcd’$bar
“‘

### *function* ppath:getatime (“‘path“‘)
Return the last access time for the “‘path“‘.

Return value is seconds since Unix Epoch (1970-01-01T00:00:00Z).

Return “‘nil“‘ if unable to access file or get its attributes.

### *function* ppath:getctime (“‘path“‘)
Return the last status change time for the “‘path“‘.

Return value is seconds since Unix Epoch (1970-01-01T00:00:00Z).

Return “‘nil“‘ if unable to access file or get its attributes.

### *function* ppath:getmtime (“‘path“‘)
Return the last modification time for the “‘path“‘.

Return value is seconds since Unix Epoch (1970-01-01T00:00:00Z).

Return “‘nil“‘ if unable to access file or get its attributes.

### *function* ppath:getsize (“‘path“‘)
Get the file size in bytes of the “‘path“‘.

Return “‘nil“‘ if unable to access file or get its attributes.

### *function* ppath:isabs (“‘path“‘)
Determine if the “‘path“‘ is an absolute pathname.

This function never checks for file existance nor address
file system but rather performs string manipulations to
determine if the “‘path“‘ is an absolute filename.

Examples (POSIX):
“‘lisp
CL-USER > (isabs "/Sources/lisp")
=> t
CL-USER > (isabs "my/dir")
=> nil
“‘

Examples (Windows):
“‘lisp
CL-USER > (isabs "\\\\host-name\\share-name\\")
=> t
“‘

### *function* ppath:isdir (“‘path“‘)
Determine if “‘path“‘ is an existing directory. If the “‘path“‘ is symlink then the invariant
“‘(and (islink path) (isdir path)) == t“‘
holds.

### *function* ppath:isfile (“‘path“‘)
Determine if the “‘path“‘ exists and a file. Returns also “‘t“‘ for symbolic links.

### *function* ppath:islink (“‘path“‘)
Determine if the “‘path“‘ is symbolic link.

On Windows always return “‘nil“‘.

### *function* ppath:ismount (“‘path“‘)
Test if the “‘path“‘ is a mount point.

On POSIX it is a directory where another filesystem is mounted.

On Windows for local paths it should be an absolute path, for UNC it should be mount point of the host

Example:
“‘lisp
CL-USER > (ismount "/mnt")
=> nil
CL-USER > (ismount "/mnt/cdrom")
=> t
“‘

### *function* ppath:join (“‘path &rest paths“‘)
Join paths provided, merging (if absolute) and
inserting missing separators.

Example:
“‘lips
CL-USER > (join "a/b" "x/y")
=> a/b\\x/y
CL-USER > (join "c:\\hello" "world/test.txt")
=> c:\\hello\\world/test.txt
CL-USER > (join "/foo" "bar" "baz")
=> /foo/bar/baz
CL-USER > (join "/foo/" "bar/" "baz/")
=> /foo/bar/baz/
“‘

### *function* ppath:lexists (“‘path“‘)
Check if the “‘path“‘ is an existing path.

Checks for existance regardless if “‘path“‘ is a link(even broken) or a file/directory.

On Windows “‘exists“‘ = “‘lexists“‘.

### *function* ppath:normcase (“‘path“‘)
Normalize the “‘path“‘.

On Windows, replace slash with backslahes and lowers the case of the “‘path“‘.

On POSIX do nothing and just return “‘path“‘.

### *function* ppath:normpath (“‘path“‘)
Normalize path, removing unnecessary/redundant parts, like dots, double slashes, etc. Expanding “‘..“‘ as well.

Example:
“‘lisp
CL-USER > (normpath "///..//./foo/.//bar")
=> /foo/bar
“‘

### *function* ppath:realpath (“‘path“‘)
Return real “‘path“‘ of the file, following symlinks if necessary. On Windows just return (abspath path). The “‘path“‘ shall be already expanded properly.

Return “‘nil“‘ if “‘path“‘ does not exist or not accessible

### *function* ppath:relpath (“‘path &optional (start ".")“‘)
Return the relative version of the “‘path“‘.

If “‘startdir“‘ provided, use this as a current directory to resolve against.

### *function* ppath:samefile (“‘path1 path2“‘)
Determine if “‘path1“‘ and “‘path2“‘ are the paths to the same file.
If one of the paths is symlink to another they considered the same.

*Not available on Windows.*

### *function* ppath:sameopenfile (“‘stream1 stream2“‘)
Determine if the open file streams “‘stream1“‘ and “‘stream2“‘ are of the same file.

*Not available on Windows.*

### *function* ppath:split (“‘path“‘)
Split the path into the pair “‘(directory . filename)“‘.
If the path ends with "/", the file component is empty.

On Windows, if the head is a drive name, the slashes are not stripped from it.

Examples:
(On Windows)
“‘lisp
CL-USER > (split "c:\\Sources\\lisp")
=> ("c:\\Sources" . "lisp")
CL-USER > (split "\\\\host-name\\share-name\\dir1\\dir2")
=> ("\\\\host-name\\share-name\\dir1" . "dir2")
“‘

(on POSIX)
“‘lisp
CL-USER > (split "/foo/bar")
=> ("/foo" . "bar")
CL-USER > (split "/foo/bar/")
=> ("/foo/bar/" . "")
“‘

### *function* ppath:splitdrive (“‘path“‘)
Split a “‘path“‘ to the drive (with letter) and path after the drive.

This function also parses the UNC paths, providing \\hostname\mountpoint as a drive part.

On POSIX drive is an empty string.

Invariant: “‘(concatenate ’string (car (splitdrive path)) (cdr (splitdrive path))) == path“‘

Example:
“‘lisp
CL-USER > (splitdrive "C:\Sources\lisp")
=> ("C:" "\Sources\lisp")
“‘

### *function* ppath:splitext (“‘path“‘)
Split “‘path“‘ to root and extension. Return a pair “‘(root . ext)“‘

If the filename component of the “‘path“‘ starts with dot, like “‘.cshrc“‘, considering no extension.

Invariant: “‘(concatenate ’string root ext) == path“‘

Examples:
“‘lisp
CL-USER > (splitext "~/test.cshrc")
=> ("~/test" . ".cshrc")
CL-USER > (splitext "~/notes.txt")
=> ("~/notes" . ".txt")
“‘

### *function* ppath:splitparts (“‘path“‘)
Split the “‘path“‘ to the list of elements using. Separators are not omitted.

Example:
“‘lisp
CL-USER > (ppath:splitparts "/abc/def/gh//12")
=> ("/" "abc" "/" "def" "/" "gh" "//" "12")
“‘

### *function* ppath:splitunc (“‘path“‘)
Split a pathname with UNC path. UNC syntax: “‘\\host-name\share-name\file_path“‘

Return a cons pair “‘("\\host-name\share-name" . "\file_path")“‘

*Not available on POSIX.*


## Author

* Alexey Veretennikov (alexey.veretennikov@gmail.com)

## Copyrights

- Python and Python documentation Copyright (c) 1990-2018, Python Software Foundation.
- Parts of Python documentation on https://docs.python.org/2.7/library/os.path.html were used and adapted when necessary to the current implementation.

## License

Licensed under the BSD License.

Version

0.1

Dependencies
  • alexandria (system).
  • cffi (system).
  • osicat (system).
  • uiop (system).
  • trivial-features (system).
  • cl-ppcre (system).
  • split-sequence (system).
Source

ppath.asd.

Child Component

src (module).


3 Modules

Modules are listed depth-first from the system components tree.


3.1 ppath/src

Source

ppath.asd.

Parent Component

ppath (system).

Child Components

3.2 ppath/src/details

Source

ppath.asd.

Parent Component

src (module).

Child Components

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


4.1 Lisp


4.1.1 ppath/ppath.asd

Source

ppath.asd.

Parent Component

ppath (system).

ASDF Systems

ppath.

Packages

ppath-asd.


4.1.2 ppath/src/details/constants.lisp

Source

ppath.asd.

Parent Component

details (module).

Packages

ppath.details.constants.

Public Interface

4.1.3 ppath/src/details/posix-cffi.lisp

Dependency

constants.lisp (file).

Source

ppath.asd.

Parent Component

details (module).

Packages

ppath.details.posix.cffi.

Public Interface

getpid (function).

Internals

4.1.4 ppath/src/details/generic.lisp

Dependency

posix-cffi.lisp (file).

Source

ppath.asd.

Parent Component

details (module).

Packages

ppath.details.generic.

Public Interface
Internals

4.1.5 ppath/src/details/posix.lisp

Dependency

generic.lisp (file).

Source

ppath.asd.

Parent Component

details (module).

Packages

ppath.details.posix.

Public Interface
Internals

4.1.6 ppath/src/ppath.lisp

Dependency

details (module).

Source

ppath.asd.

Parent Component

src (module).

Packages

ppath.

Public Interface
Internals

splitunc (function).


5 Packages

Packages are listed by definition order.


5.1 ppath.details.posix

Source

posix.lisp.

Nickname

ppath-posix

Use List
Public Interface
Internals

5.2 ppath

Source

ppath.lisp.

Use List
  • alexandria.
  • common-lisp.
Public Interface
Internals

splitunc (function).


5.3 ppath.details.posix.cffi

Source

posix-cffi.lisp.

Use List
  • alexandria.
  • cffi.
  • common-lisp.
Public Interface

getpid (function).

Internals

5.4 ppath.details.constants

Source

constants.lisp.

Use List
  • alexandria.
  • common-lisp.
Used By List
Public Interface

5.5 ppath-asd

Source

ppath.asd.

Use List
  • asdf/interface.
  • common-lisp.

5.6 ppath.details.generic

Source

generic.lisp.

Use List
Public Interface
Internals

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


6.1 Public Interface


6.1.1 Constants

Constant: +current-dir+
Package

ppath.details.constants.

Source

constants.lisp.

Constant: +path-separator+
Package

ppath.details.constants.

Source

constants.lisp.

Constant: +posix-separator+
Package

ppath.details.constants.

Source

constants.lisp.

Constant: +secs-between-epochs+

Seconds between 1.1.1601 and 1.1.1970

Package

ppath.details.constants.

Source

constants.lisp.

Constant: +sep-string+
Package

ppath.details.constants.

Source

constants.lisp.

Constant: +separator+
Package

ppath.details.constants.

Source

constants.lisp.

Constant: +unc-prefix+
Package

ppath.details.constants.

Source

constants.lisp.

Constant: +up-dir+
Package

ppath.details.constants.

Source

constants.lisp.


6.1.2 Ordinary functions

Function: abspath (path)

Return an absolute path.

Package

ppath.details.posix.

Source

posix.lisp.

Function: abspath (path)

Convert relative PATH to absolute. If path is absolute return it unchanged, if path is empty return current directory

On POSIX systems invariant:
(abspath path) == (normpath (join (getcwd) path))
holds

Package

ppath.

Source

ppath.lisp.

Function: basename (path)

Returns filename component of the PATH

Package

ppath.details.posix.

Source

posix.lisp.

Function: basename (path)

Extract the base name (filename) of the PATH.

Example:
On Windows:
CL-USER > (basename "C:\\dir\\file.txt")
=> file.txt

On POSIX:
CL-USER > (basename "/foo/bar")
=> bar

Invariant: (basename path) == (cdr (split path))

Package

ppath.

Source

ppath.lisp.

Function: commonprefix (&rest paths)

Get the common prefix substring of all strings in PATHS. The separators are not translated, so paths interpreted just as normal strings.
PATHS components could also be lists of strings, like results of
SPLIT operation on paths. In this case the comparison happens elementwise.

Example:
CL-USER > (commonprefix ’("/home/username/dir" "/home/user/test"))
=> /home/user

Package

ppath.

Source

ppath.lisp.

Function: commonprefix (&rest paths)

Get the common prefix substring of all strings in PATHS. PATHS components could also be lists of strings, like results of SPLIT operation on paths.
If no common prefix return empty string.

Package

ppath.details.generic.

Source

generic.lisp.

Function: concat (&rest strs)

Concatenate strings in a portable manner, converting to unicode string if necessary

Package

ppath.details.generic.

Source

generic.lisp.

Function: dirname (path)

Returns directory component of the PATH

Package

ppath.details.posix.

Source

posix.lisp.

Function: dirname (path)

Get the directory name of the PATH.

Example:
CL-USER > (dirname "/foo/bar")
=> /foo

Example (Windows):
CL-USER > (dirname "C:\\dir\\file.txt")
=> C:\\dir

Invariant: (dirname path) == (car (split path))

Package

ppath.

Source

ppath.lisp.

Function: exists (path)

Return true if path exists. If file is a broken link return nil

Package

ppath.details.posix.

Source

posix.lisp.

Function: exists (path)

Check if the PATH is an existing path.
On POSIX returns nil for broken symbolic links.

Package

ppath.

Source

ppath.lisp.

Function: expanduser (path)

Expand ~ and ~user inside the PATH.
If the PATH not starts with ~ it return unchanged. Return PATH unchanged if unable to expand

Package

ppath.details.posix.

Source

posix.lisp.

Function: expanduser (path)

Expand ~ and ~user in the PATH with the contents of user’s home path.
~ - home directory
~user - user’s home directory
Return PATH unchanged if unable to expand.

On Windows the path is taken either from HOME or USERPROFILE, or constructed via HOMEPATH and HOMEDRIVE.
On error just return original PATH value.
On POSIX systems the ~ is replaced with contents of the HOME environment variable or taken from password database (/etc/passwd or similar).

Examples (POSIX): (given the user "username" with home directory /Users/username)
CL-USER > (expanduser "~/dir")
=> /Users/username/dir
CL-USER > (expanduser "~root/dir")
=> /root/dir

Windows: if HOMEPATH is "users\dir" and HOMEDRIVE is "C:\\",
CL-USER > (expanduser "~test")
=> C:\users\test

Package

ppath.

Source

ppath.lisp.

Function: expandvars (path &optional modify-in-quotes)

Expand environment variables in PATH of form $VAR and ${VAR}, if variables exist. Otherwise they stay unchanged in the output. Optional argument MODIFY-IN-QUOTES if set to t (default) perform replacement inside single quotes. Otherwise strings like ’$HOME’ will left as it is.

Package

ppath.details.posix.

Source

posix.lisp.

Function: expandvars (path &optional modify-in-quotes)

Expand the PATH replacing environment variables with their contents.
The variables like ${var} and $var (and additionally %var% on Windows) are getting replaced by their values.
All unknown or malformed variables ignored and kept as it is.

The difference between Windows and Posix systems is that on Windows variables inside single quotes are not
expanded, i.e. "’$HOME’" will remain "’$HOME’", while on Posix systems it will be expanded. The optional argument MODIFY-IN-QUOTES allows to change this behavior. This behavior kept for compatibility with Python’s os.path.expandvars.

Example:
CL-USER > (expandvars "$HOME/.bashrc")
=> /home/fourier/.bashrc

CL-USER > (osicat-posix:setenv "foo" "abcd")
=> 0
CL-USER > (expandvars "’$foo’$bar" nil)
=> ’$foo’$bar
CL-USER > (expandvars "’$foo’$bar" t)
=> ’abcd’$bar

Package

ppath.

Source

ppath.lisp.

Function: get-temp-path ()

Return the path to the temporary files directory

Package

ppath.details.generic.

Source

generic.lisp.

Function: getatime (path)

Return the last access time for the PATH.
Return value is seconds since Unix Epoch (1970-01-01T00:00:00Z).

Package

ppath.details.posix.

Source

posix.lisp.

Function: getatime (path)

Return the last access time for the PATH.
Return value is seconds since Unix Epoch (1970-01-01T00:00:00Z). Return nil if unable to access file or get its attributes.

Package

ppath.

Source

ppath.lisp.

Function: getctime (path)

Return the last status change time for the PATH.
Return value is seconds since Unix Epoch (1970-01-01T00:00:00Z).

Package

ppath.details.posix.

Source

posix.lisp.

Function: getctime (path)

Return the last status change time for the PATH.
Return value is seconds since Unix Epoch (1970-01-01T00:00:00Z). Return nil if unable to access file or get its attributes.

Package

ppath.

Source

ppath.lisp.

Function: getcwd ()

Get the current working directory as a string

Package

ppath.details.generic.

Source

generic.lisp.

Function: getenv (name)

Get system environment variable value.

Package

ppath.details.generic.

Source

generic.lisp.

Function: getmtime (path)

Return the last modification time for the PATH.
Return value is seconds since Unix Epoch (1970-01-01T00:00:00Z).

Package

ppath.details.posix.

Source

posix.lisp.

Function: getmtime (path)

Return the last modification time for the PATH.
Return value is seconds since Unix Epoch (1970-01-01T00:00:00Z). Return nil if unable to access file or get its attributes.

Package

ppath.

Source

ppath.lisp.

Function: getpid ()
Package

ppath.details.posix.cffi.

Source

posix-cffi.lisp.

Function: getpid ()

Return the current process id

Package

ppath.details.generic.

Source

generic.lisp.

Function: getsize (path)

Return the file size

Package

ppath.details.posix.

Source

posix.lisp.

Function: getsize (path)

Get the file size in bytes of the PATH.
Return nil if unable to access file or get its attributes.

Package

ppath.

Source

ppath.lisp.

Function: isabs (path)

Return t if the path is absolute.

Package

ppath.details.posix.

Source

posix.lisp.

Function: isabs (path)

Determine if the PATH is an absolute pathname.
This function never checks for file existance nor address file system but rather performs string manipulations to determine if the PATH is an absolute filename.

Examples (POSIX):
CL-USER > (isabs "/Sources/lisp")
=> t
CL-USER > (isabs "my/dir")
=> nil

Examples (Windows):
CL-USER > isabs "\\\\host-name\\share-name\\")
=> t

Package

ppath.

Source

ppath.lisp.

Function: isdir (path)

Determine if the PATH is a directory

Package

ppath.details.posix.

Source

posix.lisp.

Function: isdir (path)

Determine if PATH is an existing directory. If the PATH is symlink then the invariant (and (islink PATH) (isdir PATH)) holds.

Package

ppath.

Source

ppath.lisp.

Function: isfile (path)

Determine if the PATH is a regular file

Package

ppath.details.posix.

Source

posix.lisp.

Function: isfile (path)

Determine if the PATH exists and a file. Returns also t for symbolic links.

Package

ppath.

Source

ppath.lisp.

Determine if the PATH is a symbolic link

Package

ppath.details.posix.

Source

posix.lisp.

Determine if the PATH is symbolic link. On Windows always return nil.

Package

ppath.

Source

ppath.lisp.

Function: ismount (path)

Determine if the PATH is a mount point

Package

ppath.details.posix.

Source

posix.lisp.

Function: ismount (path)

Test if the path is a mount point.
On POSIX it is a directory where another filesystem is mounted. On Windows for local paths it should be
an absolute path, for UNC it should be mount point of the host

Example:
CL-USER > (ismount "/mnt")
=> nil
CL-USER > (ismount "/mnt/cdrom")
=> t

Package

ppath.

Source

ppath.lisp.

Function: join (path &rest paths)
Package

ppath.details.posix.

Source

posix.lisp.

Function: join (path &rest paths)

Join paths provided, merging (if absolute) and inserting missing separators.

Example:
CL-USER > (join "a/b" "x/y")
=> a/b\\x/y
CL-USER > (join "c:\\hello" "world/test.txt") => c:\\hello\\world/test.txt
CL-USER > (join "/foo" "bar" "baz")
=> /foo/bar/baz
CL-USER > (join "/foo/" "bar/" "baz/")
=> /foo/bar/baz/

Package

ppath.

Source

ppath.lisp.

Function: lexists (path)

Return true if path exists, regardless if its a link(even broken) or a file/directory

Package

ppath.details.posix.

Source

posix.lisp.

Function: lexists (path)

Check if the PATH is an existing path.
Checks for existance regardless if PATH is a link(even broken) or a file/directory. On Windows exists=lexists.

Package

ppath.

Source

ppath.lisp.

Function: normcase (path)

Normalize case of PATH.
On case-sensitive file systems (default on Linux and OSX) just returns PATH unchanged

Package

ppath.details.posix.

Source

posix.lisp.

Function: normcase (path)

Normalize the PATH.
On Windows, replace slash with backslahes and lowers the case of the PATH. On POSIX do nothing and just return PATH.

Package

ppath.

Source

ppath.lisp.

Function: normpath (path)

Normalize path, removing unnecessary/redundant parts, like dots, double slashes, etc. Expanding .. as well.
Example:
///..//./foo/.//bar => /foo/bar

Package

ppath.details.posix.

Source

posix.lisp.

Function: normpath (path)

Normalize path, removing unnecessary/redundant parts, like dots, double slashes, etc. Expanding .. as well.

Example:
CL-USER > (normpath "///..//./foo/.//bar")
=> /foo/bar

Package

ppath.

Source

ppath.lisp.

Function: realpath (filename)

Return real path of the file, following symlinks if necessary

Package

ppath.details.posix.

Source

posix.lisp.

Function: realpath (path)

Return real PATH of the file, following symlinks if necessary. On Windows just return (abspath path).
The PATH shall be already expanded properly.
Return nil if PATH does not exist or not accessible

Package

ppath.

Source

ppath.lisp.

Function: relpath (path &optional start)

Convert PATH from absolute to relative

Package

ppath.details.posix.

Source

posix.lisp.

Function: relpath (path &optional start)

Return the relative version of the PATH.
If STARTDIR specified, use this as a current directory to resolve against.

Package

ppath.

Source

ppath.lisp.

Function: samefile (path1 path2)

Determine if PATH1 and PATH2 are the paths to the same file.
If one of the paths is symlink to another they considered the same.

Package

ppath.details.posix.

Source

posix.lisp.

Function: samefile (path1 path2)

Determine if PATH1 and PATH2 are the paths to the same file.
If one of the paths is symlink to another they considered the same.

Not available on Windows.

Package

ppath.

Source

ppath.lisp.

Function: sameopenfile (stream1 stream2)

Determine if the open file streams STREAM1 and STREAM2 are of the same file

Package

ppath.details.posix.

Source

posix.lisp.

Function: sameopenfile (fp1 fp2)

Determine if the open file streams STREAM1 and STREAM2 are of the same file.

Not available on Windows.

Package

ppath.

Source

ppath.lisp.

Function: split (path)

Split the path into the pair (directory . filename). If the path ends with "/", the file component is empty

Package

ppath.details.posix.

Source

posix.lisp.

Function: split (path)

Split the path into the pair (directory . filename).
If the path ends with "/", the file component is empty

On Windows, if the head is a drive name, the slashes are not stripped from it.

Examples:
(On Windows)
CL-USER > (split "c:\\Sources\\lisp")
=> ("c:\\Sources" . "lisp")
CL-USER > (split "\\\\host-name\\share-name\\dir1\\dir2")
=> ("\\\\host-name\\share-name\\dir1" . "dir2")
(on POSIX)
CL-USER > (split "/foo/bar")
=> ("/foo" . "bar")
CL-USER > (split "/foo/bar/")
=> ("/foo/bar/" . "")

Package

ppath.

Source

ppath.lisp.

Function: split-components (path)

Splits the path to the list of elements using slash as a separator. Separators are not omitted. Example:
(split-components "/abc/def/gh//12")
=> ("/" "abc" "/" "def" "/" "gh" "//" "12")

Package

ppath.details.generic.

Source

generic.lisp.

Function: splitdrive (path)

Split a path to the drive (with letter) and path after drive.
This function also parses the UNC paths, providing \\hostname\mountpoint
as a drive part.

On POSIX drive is an empty string.

Invariant: (concatenate ’string (car (splitdrive path)) (cdr (splitdrive path))) == path

Example:
CL-USER > (splitdrive "C:\Sources\lisp")
=> ("C:" "\Sources\lisp")

Package

ppath.

Source

ppath.lisp.

Function: splitext (path)

Split PATH to root and extension. Return a pair (root . ext)
If the filename component of the PATH starts with dot, like .cshrc, considering no extension. Invariant: (concatenate ’string root ext) == path

Examples:
CL-USER > (splitext "~/test.cshrc")
=> ("~/test" . ".cshrc")
CL-USER > (splitext "~/notes.txt")
=> ("~/notes" . ".txt")

Package

ppath.

Source

ppath.lisp.

Function: splitext (path)

Split path to path and extension. Extension is the text after the last dot.
Invariant: (concatenate ’string root ext) == p)

Package

ppath.details.generic.

Source

generic.lisp.

Function: splitparts (path)

Splits the path to the list of elements using. Separators are not omitted. Example:
CL-USER > (splitparts "/abc/def/gh//12")
=> ("/" "abc" "/" "def" "/" "gh" "//" "12")

Package

ppath.

Source

ppath.lisp.


6.1.3 Conditions

Condition: path-error
Package

ppath.details.generic.

Source

generic.lisp.

Direct superclasses

error.

Direct methods
Direct slots
Slot: function
Package

common-lisp.

Initform

(quote (quote ppath.details.generic::unknown))

Initargs

:function

Readers

path-error-function.

Writers

This slot is read-only.

Slot: reason
Initargs

:reason

Readers

reason.

Writers

This slot is read-only.


6.1.4 Types

Type: string-type ()
Package

ppath.details.generic.

Source

generic.lisp.


6.2 Internals


6.2.1 Constants

Constant: +path-max+
Package

ppath.details.posix.cffi.

Source

posix-cffi.lisp.


6.2.2 Macros

Macro: osicat-check-no-file (&body body)
Package

ppath.details.posix.

Source

posix.lisp.


6.2.3 Ordinary functions

Function: array-to-hex (arr)
Package

ppath.details.posix.cffi.

Source

posix-cffi.lisp.

Function: fd-from-stream (stream)

Get the posix file handle from open STREAM

Package

ppath.details.posix.

Source

posix.lisp.

Function: foreign-ptr-to-string (ptr length)
Package

ppath.details.posix.cffi.

Source

posix-cffi.lisp.

Function: getpwnam (username)

Get the list of values from DirectoryService (and /etc/passwd) by user name. Returns the list:
username
password(will have only * most likely)
user id
group id
full user name
user home directory
user shell

Package

ppath.details.posix.

Source

posix.lisp.

Function: getpwuid (uid)

Get the list of values from DirectoryService (and /etc/passwd) by user id. Returns the list:
username
password(will have only * most likely)
user id
group id
full user name
user home directory
user shell

Package

ppath.details.posix.

Source

posix.lisp.

Function: getuid ()

Get the current user id

Package

ppath.details.posix.

Source

posix.lisp.

Function: listdir (path)

Return the list of all files/directories in the PATH specified. Special names like . and .. are omitted.
No specific order assumed.
Assuming PATH is an absolute path to the directory
Return nil if not able to access

Package

ppath.details.posix.

Source

posix.lisp.

Function: or-strings (arg &rest args)

Auxulary helper function, return the first not empty string from its arguments

Package

ppath.details.posix.

Source

posix.lisp.

Function: samestat (st1 st2)

Tests if 2 osicat-posix:stat structs are the same

Package

ppath.details.posix.

Source

posix.lisp.

Function: sep-p (c)
Package

ppath.details.generic.

Source

generic.lisp.

Function: splitunc (path)

Split a pathname with UNC path. UNC syntax: \\host-name\share-name\file_path
Return a cons pair (\\host-name\share-name . \file_path)

Not available on POSIX.

Package

ppath.

Source

ppath.lisp.

Function: wildcard-to-regex (pattern &key case-sensitive-p beginning-of-string end-of-string)

Convert file wildcards to regular expressions. By default the regular
expression is case sensitive. This is regulated by keyword argument
CASE-SENSITIVE-P.
Parameters BEGINNING-OF-STRING and END-OF-STRING identify whether the beginning of the string (^) or end of string ($) marker should be present.
Supported patters:

* - everything
? - any character
[range] - any character in range
[!range] - any character not in range

Note that directory separator characters ’/’ and ’\’
are treated the same way as other characters, so
the function is used to treat complex paths they
better to be splitted.

Example:
=> (wildcard-to-regex "Photo*.jpg")
"^Photo.*\\.jpg$"
=> (wildcard-to-regex "Photo*.jpg" :case-sensitive-p nil)
"(?i)^Photo.*\\.jpg$"

Package

ppath.details.generic.

Source

generic.lisp.


6.2.4 Generic functions

Generic Reader: path-error-function (condition)
Package

ppath.details.generic.

Methods
Reader Method: path-error-function ((condition path-error))
Source

generic.lisp.

Target Slot

function.

Generic Reader: reason (condition)
Package

ppath.details.generic.

Methods
Reader Method: reason ((condition path-error))
Source

generic.lisp.

Target Slot

reason.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   A   B   C   D   E   F   G   I   J   L   M   N   O   P   R   S   W  
Index Entry  Section

A
abspath: Public ordinary functions
abspath: Public ordinary functions
array-to-hex: Private ordinary functions

B
basename: Public ordinary functions
basename: Public ordinary functions

C
commonprefix: Public ordinary functions
commonprefix: Public ordinary functions
concat: Public ordinary functions

D
dirname: Public ordinary functions
dirname: Public ordinary functions

E
exists: Public ordinary functions
exists: Public ordinary functions
expanduser: Public ordinary functions
expanduser: Public ordinary functions
expandvars: Public ordinary functions
expandvars: Public ordinary functions

F
fd-from-stream: Private ordinary functions
foreign-ptr-to-string: Private ordinary functions
Function, abspath: Public ordinary functions
Function, abspath: Public ordinary functions
Function, array-to-hex: Private ordinary functions
Function, basename: Public ordinary functions
Function, basename: Public ordinary functions
Function, commonprefix: Public ordinary functions
Function, commonprefix: Public ordinary functions
Function, concat: Public ordinary functions
Function, dirname: Public ordinary functions
Function, dirname: Public ordinary functions
Function, exists: Public ordinary functions
Function, exists: Public ordinary functions
Function, expanduser: Public ordinary functions
Function, expanduser: Public ordinary functions
Function, expandvars: Public ordinary functions
Function, expandvars: Public ordinary functions
Function, fd-from-stream: Private ordinary functions
Function, foreign-ptr-to-string: Private ordinary functions
Function, get-temp-path: Public ordinary functions
Function, getatime: Public ordinary functions
Function, getatime: Public ordinary functions
Function, getctime: Public ordinary functions
Function, getctime: Public ordinary functions
Function, getcwd: Public ordinary functions
Function, getenv: Public ordinary functions
Function, getmtime: Public ordinary functions
Function, getmtime: Public ordinary functions
Function, getpid: Public ordinary functions
Function, getpid: Public ordinary functions
Function, getpwnam: Private ordinary functions
Function, getpwuid: Private ordinary functions
Function, getsize: Public ordinary functions
Function, getsize: Public ordinary functions
Function, getuid: Private ordinary functions
Function, isabs: Public ordinary functions
Function, isabs: Public ordinary functions
Function, isdir: Public ordinary functions
Function, isdir: Public ordinary functions
Function, isfile: Public ordinary functions
Function, isfile: Public ordinary functions
Function, islink: Public ordinary functions
Function, islink: Public ordinary functions
Function, ismount: Public ordinary functions
Function, ismount: Public ordinary functions
Function, join: Public ordinary functions
Function, join: Public ordinary functions
Function, lexists: Public ordinary functions
Function, lexists: Public ordinary functions
Function, listdir: Private ordinary functions
Function, normcase: Public ordinary functions
Function, normcase: Public ordinary functions
Function, normpath: Public ordinary functions
Function, normpath: Public ordinary functions
Function, or-strings: Private ordinary functions
Function, realpath: Public ordinary functions
Function, realpath: Public ordinary functions
Function, relpath: Public ordinary functions
Function, relpath: Public ordinary functions
Function, samefile: Public ordinary functions
Function, samefile: Public ordinary functions
Function, sameopenfile: Public ordinary functions
Function, sameopenfile: Public ordinary functions
Function, samestat: Private ordinary functions
Function, sep-p: Private ordinary functions
Function, split: Public ordinary functions
Function, split: Public ordinary functions
Function, split-components: Public ordinary functions
Function, splitdrive: Public ordinary functions
Function, splitext: Public ordinary functions
Function, splitext: Public ordinary functions
Function, splitparts: Public ordinary functions
Function, splitunc: Private ordinary functions
Function, wildcard-to-regex: Private ordinary functions

G
Generic Function, path-error-function: Private generic functions
Generic Function, reason: Private generic functions
get-temp-path: Public ordinary functions
getatime: Public ordinary functions
getatime: Public ordinary functions
getctime: Public ordinary functions
getctime: Public ordinary functions
getcwd: Public ordinary functions
getenv: Public ordinary functions
getmtime: Public ordinary functions
getmtime: Public ordinary functions
getpid: Public ordinary functions
getpid: Public ordinary functions
getpwnam: Private ordinary functions
getpwuid: Private ordinary functions
getsize: Public ordinary functions
getsize: Public ordinary functions
getuid: Private ordinary functions

I
isabs: Public ordinary functions
isabs: Public ordinary functions
isdir: Public ordinary functions
isdir: Public ordinary functions
isfile: Public ordinary functions
isfile: Public ordinary functions
islink: Public ordinary functions
islink: Public ordinary functions
ismount: Public ordinary functions
ismount: Public ordinary functions

J
join: Public ordinary functions
join: Public ordinary functions

L
lexists: Public ordinary functions
lexists: Public ordinary functions
listdir: Private ordinary functions

M
Macro, osicat-check-no-file: Private macros
Method, path-error-function: Private generic functions
Method, reason: Private generic functions

N
normcase: Public ordinary functions
normcase: Public ordinary functions
normpath: Public ordinary functions
normpath: Public ordinary functions

O
or-strings: Private ordinary functions
osicat-check-no-file: Private macros

P
path-error-function: Private generic functions
path-error-function: Private generic functions

R
realpath: Public ordinary functions
realpath: Public ordinary functions
reason: Private generic functions
reason: Private generic functions
relpath: Public ordinary functions
relpath: Public ordinary functions

S
samefile: Public ordinary functions
samefile: Public ordinary functions
sameopenfile: Public ordinary functions
sameopenfile: Public ordinary functions
samestat: Private ordinary functions
sep-p: Private ordinary functions
split: Public ordinary functions
split: Public ordinary functions
split-components: Public ordinary functions
splitdrive: Public ordinary functions
splitext: Public ordinary functions
splitext: Public ordinary functions
splitparts: Public ordinary functions
splitunc: Private ordinary functions

W
wildcard-to-regex: Private ordinary functions


A.4 Data types

Jump to:   C   D   F   G   M   P   S   T  
Index Entry  Section

C
Condition, path-error: Public conditions
constants.lisp: The ppath/src/details/constants․lisp file

D
details: The ppath/src/details module

F
File, constants.lisp: The ppath/src/details/constants․lisp file
File, generic.lisp: The ppath/src/details/generic․lisp file
File, posix-cffi.lisp: The ppath/src/details/posix-cffi․lisp file
File, posix.lisp: The ppath/src/details/posix․lisp file
File, ppath.asd: The ppath/ppath․asd file
File, ppath.lisp: The ppath/src/ppath․lisp file

G
generic.lisp: The ppath/src/details/generic․lisp file

M
Module, details: The ppath/src/details module
Module, src: The ppath/src module

P
Package, ppath: The ppath package
Package, ppath-asd: The ppath-asd package
Package, ppath.details.constants: The ppath․details․constants package
Package, ppath.details.generic: The ppath․details․generic package
Package, ppath.details.posix: The ppath․details․posix package
Package, ppath.details.posix.cffi: The ppath․details․posix․cffi package
path-error: Public conditions
posix-cffi.lisp: The ppath/src/details/posix-cffi․lisp file
posix.lisp: The ppath/src/details/posix․lisp file
ppath: The ppath system
ppath: The ppath package
ppath-asd: The ppath-asd package
ppath.asd: The ppath/ppath․asd file
ppath.details.constants: The ppath․details․constants package
ppath.details.generic: The ppath․details․generic package
ppath.details.posix: The ppath․details․posix package
ppath.details.posix.cffi: The ppath․details․posix․cffi package
ppath.lisp: The ppath/src/ppath․lisp file

S
src: The ppath/src module
string-type: Public types
System, ppath: The ppath system

T
Type, string-type: Public types