The pathname-utils Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The pathname-utils Reference Manual

This is the pathname-utils Reference Manual, version 1.1.0, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 04:24:14 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

About Pathname-Utils

This is a collection of common tests and operations to help handling pathnames. It does not actually deal in handling the accessing of files on the underlying system however.

How To

Since this is a purely utility/toolkit library, simply having a look at the symbol index should give you the best idea of what is offered.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 pathname-utils

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

https://github.com/Shinmera/pathname-utils

License

Artistic

Description

A collection of utilities for pathname manipulation.

Version

1.1.0

Source

pathname-utils.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 pathname-utils.asd

Location

pathname-utils.asd

Systems

pathname-utils (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 pathname-utils/package.lisp

Parent

pathname-utils (system)

Location

package.lisp

Packages

pathname-utils


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 pathname-utils/toolkit.lisp

Dependency

package.lisp (file)

Parent

pathname-utils (system)

Location

toolkit.lisp

Exported Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.4 pathname-utils/documentation.lisp

Dependency

toolkit.lisp (file)

Parent

pathname-utils (system)

Location

documentation.lisp

Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 pathname-utils

Source

package.lisp (file)

Nickname

org.shirakumo.pathname-utils

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

Special Variable: *wild-component*

The proper value to use for a wild pathname component.

Package

pathname-utils

Source

toolkit.lisp (file)

Special Variable: *wild-directory*

A pathname that is wild in its directory spec (can match any directory).

Package

pathname-utils

Source

toolkit.lisp (file)

Special Variable: *wild-file*

A pathname that is wild in its file spec (can match any file).

Package

pathname-utils

Source

toolkit.lisp (file)

Special Variable: *wild-inferiors*

A pathname that has wild inferiors (can match any number of subdirectories).

Package

pathname-utils

Source

toolkit.lisp (file)

Special Variable: *wild-inferiors-component*

The proper value to use for a wild inferiors pathname component.

Package

pathname-utils

Source

toolkit.lisp (file)

Special Variable: *wild-path*

A pathname that is wild in both its file and its directory.

Package

pathname-utils

Source

toolkit.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Function: absolute-p PATHNAME

Returns the pathname if it is an absolute pathname.

The pathname is coerced using PATHNAME*

See PATHNAME*

Package

pathname-utils

Source

toolkit.lisp (file)

Function: clean-directory-spec DIR

Removes superfluous components from the directory spec.

Specifically, if the encountered part is UNSPECIFIC or the string ".", it is omitted. If the part is :BACK, the preceding component is omitted if possible. If not possible, an equivalent amount of :UP specs are inserted instead.

Package

pathname-utils

Source

toolkit.lisp (file)

Function: components PATHNAME

Returns a plist containing all the components making up the given pathname.

The plist contains the following keys:
:namestring
:truename
:host
:device
:name
:type
:version
:directory

If the pathname has no truename, its value in the plist is NIL.

Package

pathname-utils

Source

toolkit.lisp (file)

Function: directory-name PATHNAME

Returns the name of the topmost directory in the pathname, if any.

The pathname is coerced using TO-DIRECTORY

See TO-DIRECTORY

Package

pathname-utils

Source

toolkit.lisp (file)

Function: directory-p PATHNAME

Returns the pathname if it denotes a directory (not a file).

The pathname is coerced using PATHNAME*

See PATHNAME*

Package

pathname-utils

Source

toolkit.lisp (file)

Function: directory-separator &optional PATHNAME

Returns the namestring separator between directories as a string.

Package

pathname-utils

Source

toolkit.lisp (file)

Function: downwards PATHNAME SUBDIR

Moves the topmost pathname component a level downwards.

Specifically, if we have a file "foo/bar.jpg", and move it downwards by "baz", the resulting pathname will be "foo/baz/bar.jpg". If the pathname is a directory-pathname then the last directory is moved downwards by one.

See SUBDIRECTORY

Package

pathname-utils

Source

toolkit.lisp (file)

Function: enough-pathname SUBPATH BASE

Like ENOUGH-NAMESTRING but returns an actual pathname.

The pathname is coerced using PATHNAME*

See PATHNAME*

Package

pathname-utils

Source

toolkit.lisp (file)

Function: file-name PATHNAME

Returns the complete file name as it would be used by the OS, if any.

Package

pathname-utils

Source

toolkit.lisp (file)

Function: file-p PATHNAME

Returns the pathname if it denotes a file (not a directory).

The pathname is coerced using PATHNAME*

See PATHNAME*

Package

pathname-utils

Source

toolkit.lisp (file)

Function: file-type PATHNAME

Returns the actual file type.

This is different from PATHNAME-TYPE in the following manner: If PATHNAME-TYPE is specific, but contains a dot, only the part after the dot is used as it would indicate the actual file-type on any recent system. If PATHNAME-TYPE is unspecific, the PATHNAME-NAME is specific, and it contains a dot, then that last part is used instead. Otherwise NIL is returned.

Package

pathname-utils

Source

toolkit.lisp (file)

Function: logical-p PATHNAME

Returns the pathname if it is a logical pathname.

The pathname is coerced using PATHNAME*

See PATHNAME*

Package

pathname-utils

Source

toolkit.lisp (file)

Function: normalize-directory-spec DIR

Attempts to normalize the directory specification into one as specified by CLHS.

Also cleans the directory spec.

See CLEAN-DIRECTORY-SPEC.

Package

pathname-utils

Source

toolkit.lisp (file)

Function: normalize-pathname PATHNAME

Returns a normalised form of the given pathname.

More specifically, the given object is ensured to be a pathname using CL:PATHNAME, then turned into a new pathname with the following properties: an unspecific component is turned into NIL and the directory component is normalised through NORMALIZE-DIRECTORY-SPEC.

See UNSPECIFIC-P
See NORMALIZE-DIRECTORY-SPEC

Package

pathname-utils

Source

toolkit.lisp (file)

Function: parent PATHNAME

Returns the parent of the pathname.

If the pathname is a directory-pathname, it returns a pathname that points to the parent thereof, if possible. Specifically, if the directory is relative and empty, :up is inserted. If it is absolute and empty, the same pathname is returned. If it is not empty, then the last component of the directory is removed. If the pathname is a file pathname, this is equivalent to TO-DIRECTORY.

The pathname is coerced using PATHNAME*.

If you need to preserve the pathname’s file component, consider using UPWARDS instead.

See PATHNAME*
See TO-DIRECTORY

Package

pathname-utils

Source

toolkit.lisp (file)

Function: pathname* PATHNAME

Ensures that the argument is a pathname.

If a pathname is passed, it is returned verbatim.
If it is anything else, the value is coerced to a pathname using NORMALIZE-PATHNAME.

See NORMALIZE-PATHNAME

Package

pathname-utils

Source

toolkit.lisp (file)

Function: pathname-equal A B

Returns T if the two pathnames denote the same file.

Note that this comparison has to access the file system and might therefore be costly.

First the two pathnames are turned into truenames using TRUENAME and then compared using PATHNAME=. This should result in a comparison that returns true in any situation where the two pathnames really do refer to the same file, but might not look the same due to symbolic links or similar effects in the file system.

See CL:TRUENAME
See PATHNAME=

Package

pathname-utils

Source

toolkit.lisp (file)

Function: pathname= A B &key IGNORE-VERSION

Returns T if the two pathnames are the same.

Note that this comparison is purely based on the pathnames itself and does not check whether the two might resolve to the same file on the system.

Relative pathnames are turned into absolute ones by merging them with *default-pathname-defaults* before being compared.

Each component of the pathnames are compared using EQUAL, but treating parts that are UNSPECIFIC-P as the same, regardless of the way in which they might be unspecific.

If IGNORE-VERSION is non-NIL (the default), then the version component of the pathnames is not compared. This is useful, as it can be different for pathnames that appear to be the same on some implementations.

See UNSPECIFIC-P

Package

pathname-utils

Source

toolkit.lisp (file)

Function: physical-p PATHNAME

Returns the pathname if it is a physical pathname.

The pathname is coerced using PATHNAME*

See PATHNAME*

Package

pathname-utils

Source

toolkit.lisp (file)

Function: pop-directory PATHNAME

Pops the last component off the pathname-directory part.

The pathname is coerced using PATHNAME*.
Note that this will probably not behave as expected for pathnames containing :back and :up. For the "intuitive" behaviour to ascend pathnames, see PARENT or UPWARDS.

See PATHNAME*

Package

pathname-utils

Source

toolkit.lisp (file)

Function: relative-p PATHNAME

Returns the pathname if it is a relative pathname.

The pathname is coerced using PATHNAME*

See PATHNAME*

Package

pathname-utils

Source

toolkit.lisp (file)

Function: relative-pathname FROM TO

Computes a relative pathname from one place to another.

The pathnames are first turned into absolute ones by MERGE-PATHNAMES. Then, the common directory components are eliminated, leftover directory components on the from path are converted into :up, and finally the remaining components of the to path are appended, producing the final directory component. The name, type, and version are taken from the to pathname.

If the two pathnames differ in device or host, an error is signalled instead.

The pathnames are coerced using NORMALIZE-PATHNAME after the merge.

See NORMALIZE-PATHNAME

Package

pathname-utils

Source

toolkit.lisp (file)

Function: root-p PATHNAME

Returns the pathname if it denotes an absolute root directory.

The pathname is coerced using PATHNAME*

See PATHNAME*

Package

pathname-utils

Source

toolkit.lisp (file)

Function: subdirectory PATHNAME &rest SUBDIRS

Returns a directory-pathname with the given subdirectories appended.

For example, appending "bar" and "baz" to "foo/" will
result in "foo/bar/baz/".

The PATHNAME is coerced using TO-DIRECTORY. For any of the subdirs, if it is a pathname, stream, or keyword, it is coerced to a pathname using TO-DIRECTORY. If it is a string, it is coerced using TO-DIRECTORY but with a trailing slash appended.

If you need to preserve the pathname’s file component, consider using DOWNWARDS instead.

See TO-DIRECTORY

Package

pathname-utils

Source

toolkit.lisp (file)

Function: subpath-p SUBPATH BASE &optional ROOT

Returns true if SUBPATH denotes a path on a lower level than BASE.

A pathname is considered a subpath of a base pathname if all of the following are true:
- Their hosts match
- Their devices match
- The base’s name is null or their names match
- The base’s type is null or their types match
- The directory component of the subpath denotes a subdirectory of the directory component of the base.

If the subpath or base are relative pathnames, they are made absolute by merging them with the root pathname. If the root pathname is relative, an error is signalled.

The actually returned value is the coerced value of SUBPATH by NORMALIZE-PATHNAME.

See NORMALIZE-PATHNAME

Package

pathname-utils

Source

toolkit.lisp (file)

Function: to-directory PATHNAME

Turns the pathname into a pathname-directory if it is not already one.

If the argument is :UP or :BACK, it is turned into a relative pathname with the argument as its only pathname-directory-component. If the argument is :HOME, it is turned into an absolute pathname pointing to the home directory.
Otherwise the pathname is coerced using PATHNAME*

See PATHNAME*

Package

pathname-utils

Source

toolkit.lisp (file)

Function: to-file PATHNAME

Turns the pathname into a file pathname.

This means stripping the device, host, and directory components of the pathname. The given pathname is coerced using PATHNAME*

See PATHNAME*

Package

pathname-utils

Source

toolkit.lisp (file)

Function: to-physical PATHNAME

Turns the pathname into a physical one if it is not already one.

The pathname is coerced using PATHNAME*

See LOGICAL-P
See CL:TRANSLATE-LOGICAL-PATHNAME
See PATHNAME*

Package

pathname-utils

Source

toolkit.lisp (file)

Function: to-root PATHNAME

Returns the absolute root of the pathname.

Package

pathname-utils

Source

toolkit.lisp (file)

Function: unspecific-p COMPONENT

Returns true if the given component is unspecific.

This includes :UNSPECIFIC, NIL, and the empty string.

Package

pathname-utils

Source

toolkit.lisp (file)

Function: upwards PATHNAME

Moves the topmost pathname component a level upwards.

Specifically, if we have a file "foo/bar/baz.jpg", and move it upwards by one, the resulting pathname will be "foo/baz.jpg". If the pathname is a directory-pathname then the last directory is moved upwards by one.

See PARENT

Package

pathname-utils

Source

toolkit.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Macros

Macro: setdocs &body PAIRS

Easily set the documentation.

Package

pathname-utils

Source

documentation.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: checkdocs &optional PACKAGE

Check that all functions, classes, and variables have docstrings.

Package

pathname-utils

Source

documentation.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   P  
Index Entry  Section

F
File, Lisp, pathname-utils.asd: The pathname-utils<dot>asd file
File, Lisp, pathname-utils/documentation.lisp: The pathname-utils/documentation<dot>lisp file
File, Lisp, pathname-utils/package.lisp: The pathname-utils/package<dot>lisp file
File, Lisp, pathname-utils/toolkit.lisp: The pathname-utils/toolkit<dot>lisp file

L
Lisp File, pathname-utils.asd: The pathname-utils<dot>asd file
Lisp File, pathname-utils/documentation.lisp: The pathname-utils/documentation<dot>lisp file
Lisp File, pathname-utils/package.lisp: The pathname-utils/package<dot>lisp file
Lisp File, pathname-utils/toolkit.lisp: The pathname-utils/toolkit<dot>lisp file

P
pathname-utils.asd: The pathname-utils<dot>asd file
pathname-utils/documentation.lisp: The pathname-utils/documentation<dot>lisp file
pathname-utils/package.lisp: The pathname-utils/package<dot>lisp file
pathname-utils/toolkit.lisp: The pathname-utils/toolkit<dot>lisp file

Jump to:   F   L   P  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   A   C   D   E   F   L   M   N   P   R   S   T   U  
Index Entry  Section

A
absolute-p: Exported functions

C
checkdocs: Internal functions
clean-directory-spec: Exported functions
components: Exported functions

D
directory-name: Exported functions
directory-p: Exported functions
directory-separator: Exported functions
downwards: Exported functions

E
enough-pathname: Exported functions

F
file-name: Exported functions
file-p: Exported functions
file-type: Exported functions
Function, absolute-p: Exported functions
Function, checkdocs: Internal functions
Function, clean-directory-spec: Exported functions
Function, components: Exported functions
Function, directory-name: Exported functions
Function, directory-p: Exported functions
Function, directory-separator: Exported functions
Function, downwards: Exported functions
Function, enough-pathname: Exported functions
Function, file-name: Exported functions
Function, file-p: Exported functions
Function, file-type: Exported functions
Function, logical-p: Exported functions
Function, normalize-directory-spec: Exported functions
Function, normalize-pathname: Exported functions
Function, parent: Exported functions
Function, pathname*: Exported functions
Function, pathname-equal: Exported functions
Function, pathname=: Exported functions
Function, physical-p: Exported functions
Function, pop-directory: Exported functions
Function, relative-p: Exported functions
Function, relative-pathname: Exported functions
Function, root-p: Exported functions
Function, subdirectory: Exported functions
Function, subpath-p: Exported functions
Function, to-directory: Exported functions
Function, to-file: Exported functions
Function, to-physical: Exported functions
Function, to-root: Exported functions
Function, unspecific-p: Exported functions
Function, upwards: Exported functions

L
logical-p: Exported functions

M
Macro, setdocs: Internal macros

N
normalize-directory-spec: Exported functions
normalize-pathname: Exported functions

P
parent: Exported functions
pathname*: Exported functions
pathname-equal: Exported functions
pathname=: Exported functions
physical-p: Exported functions
pop-directory: Exported functions

R
relative-p: Exported functions
relative-pathname: Exported functions
root-p: Exported functions

S
setdocs: Internal macros
subdirectory: Exported functions
subpath-p: Exported functions

T
to-directory: Exported functions
to-file: Exported functions
to-physical: Exported functions
to-root: Exported functions

U
unspecific-p: Exported functions
upwards: Exported functions

Jump to:   A   C   D   E   F   L   M   N   P   R   S   T   U  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*wild-component*: Exported special variables
*wild-directory*: Exported special variables
*wild-file*: Exported special variables
*wild-inferiors*: Exported special variables
*wild-inferiors-component*: Exported special variables
*wild-path*: Exported special variables

S
Special Variable, *wild-component*: Exported special variables
Special Variable, *wild-directory*: Exported special variables
Special Variable, *wild-file*: Exported special variables
Special Variable, *wild-inferiors*: Exported special variables
Special Variable, *wild-inferiors-component*: Exported special variables
Special Variable, *wild-path*: Exported special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   P   S  
Index Entry  Section

P
Package, pathname-utils: The pathname-utils package
pathname-utils: The pathname-utils system
pathname-utils: The pathname-utils package

S
System, pathname-utils: The pathname-utils system

Jump to:   P   S