The illogical-pathnames Reference Manual

Table of Contents

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

The illogical-pathnames Reference Manual

This is the illogical-pathnames Reference Manual, version 1.0.1, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 04:04:23 2018 GMT+0.


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

1 Introduction

                         ILLOGICAL PATHNAMES
                         ===================

                           By Robert Smith


Purpose
-------

The purpose of this library is to allow one to specify pathnames in
source files whose syntax mostly doesn't depend on a physical path
location. To put it simply, one can write

    #P(:HOME (".emacs.d") "foo.el")

instead of

    #P"/home/me/.emacs.d/foo.el".

Somewhere, :HOME---a so-called "illogical host"---has to be
specified. This is done by associating it with a directory via the
macro DEFINE-ILLOGICAL-HOST. They can be redefined, which won't affect
evaluated uses of #P(...) syntax.

The former syntax isn't actually an "illogical pathname"; it evaluates
to a physical pathname. (See the example below and the FAQ.) However,
it does involve objects of the type ILLOGICAL-PATHNAME under the hood.

Using illogical pathnames allows one to easily write code whose
pathnames are relative to a few known base directories. When the
program is moved, or perhaps an executable is created, one only has to
redefine the set of illogical hosts. Using the power of
*LOAD-TRUENAME* and others, one can make mostly portable applications
that don't depend on physical filesystem location at all.


Name
----

Before this library, I attempted to solve the same problem by defining
logical hosts with wildcard translations. This worked relatively well
with Clozure CL, due to their more flexible implementation of logical
pathnames. However, more ANSI compliant systems (with respect to
logical pathnames) didn't work with the same code. As such, in my
mind, I made "logical pathnames that solve the 95% case" and called
them "illogical pathnames", a play on the fact that they were supposed
to be "logical logical pathnames". (A double positive makes a
negative, right?)

Despite the name and the reasoning behind the name, these aren't a
replacement for logical pathnames and are not "better" than logical
pathnames; they just solve a different problem than that which logical
hosts solve on modern machines.


Example
-------

Note that normal pathname syntax isn't changed.

    > #P"/foo/bar"
    #P"/foo/bar"

Let's define an illogical host that points to my home directory.

    > (ipath:define-illogical-host :home "/home/me/")
    :HOME

Let's use the extended pathname syntax to refer to a file in my home
directory.

    > #P(:home ("Scratch") "new.txt")
    #P"/home/me/Scratch/new.txt"

We see that #P(...) isn't truly a literal for an illogical
pathname. It returned a physical pathname. What does #P(...) really
expand into then?

    > '#P(:home ("Scratch") "new.txt")
    (ILLOGICAL-PATHNAMES:TRANSLATE-ILLOGICAL-PATHNAME
      #S(ILLOGICAL-PATHNAMES:ILLOGICAL-PATHNAME
          :HOST :HOME
          :DIRECTORY ("Scratch")
          :NAME "new"
          :TYPE "txt"))

Just an unevaluated translation of an illogical pathname object.

Let's define another illogical host referring to my scratch space
directory in my home directory.

    > (ipath:define-illogical-host :scratch #P(:home ("Scratch")))
    :SCRATCH

Let's open a new file and write to it in my scratch space.

    > (with-open-file (s #P(:scratch nil "test.txt") :direction ':output
                                                     :if-does-not-exist ':create)
        (write-string "testing, 1 2 3" s))
    "testing, 1 2 3"

And finally, let's read it back.

    > (with-open-file (s #P(:scratch nil "test.txt") :direction ':input)
        (read-line s))
    "testing, 1 2 3"
     T

That is basically it.


Frequently Asked Questions
--------------------------

Q. Why doesn't #P(...) specify a literal illogical pathname object?

This was a pragmatic choice. If Common Lisp had a generic function
called, say, TRANSLATE-TO-PATHNAME which all relevant Common Lisp
functions knew about, we could indeed use illogical pathname objects
by creating a method of that generic function. However, since we don't
have that functionality, yet we want to relatively transparently be
able to specify illogical pathnames in the places they're used, we do
the translation within the expansion of #P(...).


Q. My system needs to be bootstrapped, and I can't rely on Quicklisp
   or ASDF, but I want to use illogical pathnames.

No problem. The file "illogical-pathnames.lisp" is self-contained. You
can load it as-is.


Q. ANSI logical pathnames can solve this problem. I tried it and
   it works fine!
   
The ANSI spec requires that strings in logical pathnames must be uppercase,
and the system should convert them to uppercase when pathnames are created:

"Logical pathname words are restricted to non-case-sensitive letters,
digits, and hyphens to avoid creating problems with real file systems
that support limited character sets for file naming. (If logical pathnames
were case-sensitive, it would be very difficult to map them into a file
system that is not sensitive to case in its file names.)"

https://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node213.html

The phrase in parentheses above is precisely the opposite of the truth.
A fully ANSI-conforming logical pathname implementation cannot generally
be used on a case-sensitive file system such as that typically used in Linux
or Unix.

If you are not seeing this problem with your CL implementation, it is either because
you are using a case-insensitive file system like MacOSX, or because
your implementation (e.g., Clozure CL or Franz) sanely nixed the ANSI idea
of logical pathnames and made them case-preserving.
Unfortunately, that is not ANSI conforming.


Q. Why didn't you just make a DEFINE-* macro and a function?

Pathnames need to be convenient, and specifying functions in full is
not syntactically convenient. If one doesn't like the #P syntax, they
may opt to create ILLOGICAL-PATHNAME objects and call
TRANSLATE-ILLOGICAL-PATHNAME at will.

       > (ipath:define-illogical-host :home "/Users/me/")
       :HOME
       > (ipath:make-illogical-pathname
          :host ':home
          :directory '("foo" "bar")
          :name "test"
          :type "txt")
       #S(ILLOGICAL-PATHNAMES:ILLOGICAL-PATHNAME :HOST :HOME :DIRECTORY ("foo" "bar") :NAME "test" :TYPE "txt")
       > (ipath:translate-illogical-pathname *)
       #P"/Users/me/foo/bar/test.txt"


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 illogical-pathnames

Author

Robert Smith <quad@symbo1ics.com>

License

BSD 3-clause (See illogical-pathnames.lisp)

Description

Mostly filesystem-position-independent pathnames.

Version

1.0.1

Source

illogical-pathnames.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.


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

3.1 Lisp


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

3.1.1 illogical-pathnames.asd

Location

illogical-pathnames.asd

Systems

illogical-pathnames (system)


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

3.1.2 illogical-pathnames/illogical-pathnames.lisp

Dependency

readme.txt (file)

Parent

illogical-pathnames (system)

Location

illogical-pathnames.lisp

Packages

illogical-pathnames

Exported Definitions
Internal Definitions

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

3.2 Other


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

3.2.1 illogical-pathnames/README.txt

Parent

illogical-pathnames (system)

Location

README.txt


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

4 Packages

Packages are listed by definition order.


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

4.1 illogical-pathnames

Source

illogical-pathnames.lisp (file)

Nickname

ipath

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 Macros

Macro: define-illogical-host HOST DIRECTORY &optional DOCUMENTATION

Define the illogical host HOST to the absolute directory DIRECTORY.

Package

illogical-pathnames

Source

illogical-pathnames.lisp (file)


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

5.1.2 Functions

Function: disable-illogical-pathname-syntax ()

Disable illogical pathname syntax.

Package

illogical-pathnames

Source

illogical-pathnames.lisp (file)

Function: enable-illogical-pathname-syntax ()

Enable illogical pathname syntax.

#P"..." ; traditional pathname syntax

#P(<illogical-host> (<directory name>*) <filename>?)

Package

illogical-pathnames

Source

illogical-pathnames.lisp (file)

Function: illogical-host-translation ILLOGICAL-HOST

Translate the illogical host ILLOGICAL-HOST to its defined absolute directory.

Package

illogical-pathnames

Source

illogical-pathnames.lisp (file)

Writer

(setf illogical-host-translation) (function)

Function: (setf illogical-host-translation) DIRECTORY ILLOGICAL-HOST
Package

illogical-pathnames

Source

illogical-pathnames.lisp (file)

Reader

illogical-host-translation (function)

Function: illogical-pathname-directory INSTANCE
Function: (setf illogical-pathname-directory) VALUE INSTANCE
Package

illogical-pathnames

Source

illogical-pathnames.lisp (file)

Function: illogical-pathname-host INSTANCE
Function: (setf illogical-pathname-host) VALUE INSTANCE
Package

illogical-pathnames

Source

illogical-pathnames.lisp (file)

Function: illogical-pathname-name INSTANCE
Function: (setf illogical-pathname-name) VALUE INSTANCE
Package

illogical-pathnames

Source

illogical-pathnames.lisp (file)

Function: illogical-pathname-p OBJECT
Package

illogical-pathnames

Source

illogical-pathnames.lisp (file)

Function: illogical-pathname-type INSTANCE
Function: (setf illogical-pathname-type) VALUE INSTANCE
Package

illogical-pathnames

Source

illogical-pathnames.lisp (file)

Function: make-illogical-pathname &key (HOST HOST) (DIRECTORY DIRECTORY) (NAME NAME) (TYPE TYPE)
Package

illogical-pathnames

Source

illogical-pathnames.lisp (file)

Function: translate-illogical-pathname ILLOGICAL-PATHNAME

Translate the illogical pathname ILLOGICAL-PATHNAME to its equivalent absolute pathname.

Package

illogical-pathnames

Source

illogical-pathnames.lisp (file)


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

5.1.3 Structures

Structure: illogical-pathname ()
Package

illogical-pathnames

Source

illogical-pathnames.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods

make-load-form (method)

Direct slots
Slot: host
Readers

illogical-pathname-host (function)

Writers

(setf illogical-pathname-host) (function)

Slot: directory
Readers

illogical-pathname-directory (function)

Writers

(setf illogical-pathname-directory) (function)

Slot: name
Readers

illogical-pathname-name (function)

Writers

(setf illogical-pathname-name) (function)

Slot: type
Readers

illogical-pathname-type (function)

Writers

(setf illogical-pathname-type) (function)


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

5.1.4 Types

Type: illogical-host ()

The type of an illogical host object.

Package

illogical-pathnames

Source

illogical-pathnames.lisp (file)


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

5.2 Internal definitions


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

5.2.1 Special variables

Special Variable: *common-lisp-sharp-p*
Package

illogical-pathnames

Source

illogical-pathnames.lisp (file)

Special Variable: *illogical-hosts*

Association between ILLOGICAL-HOSTs and their pathname translation.

Package

illogical-pathnames

Source

illogical-pathnames.lisp (file)


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

5.2.2 Functions

Function: component-present-p VALUE

Helper function for DIRECTORY-PATHNAME-P which checks whether VALUE is neither NIL nor the keyword :UNSPECIFIC.

Package

illogical-pathnames

Source

illogical-pathnames.lisp (file)

Function: copy-illogical-pathname INSTANCE
Package

illogical-pathnames

Source

illogical-pathnames.lisp (file)

Function: directory-pathname-p PATHSPEC

Returns NIL if PATHSPEC (a pathname designator) does not designate a directory, PATHSPEC otherwise. It is irrelevant whether file or directory designated by PATHSPEC does actually exist.

Package

illogical-pathnames

Source

illogical-pathnames.lisp (file)

Function: illogical-#p-reader STREAM SUBCHAR ARG

Reader for illogical pathnames. Returns an illogical pathname.

Package

illogical-pathnames

Source

illogical-pathnames.lisp (file)

Function: illogical-pathname-relative-pathname ILLOGICAL-PATHNAME

Convert the illogical pathname ILLOGICAL-PATHNAME to its representative relative pathname.

Package

illogical-pathnames

Source

illogical-pathnames.lisp (file)

Function: new-#p-reader STREAM SUBCHAR ARG
Package

illogical-pathnames

Source

illogical-pathnames.lisp (file)

Function: pathname-absolute-p A

Returns true if A is an absolute pathname.

This simply tests if A’s directory list starts with :ABSOLUTE

Package

illogical-pathnames

Source

illogical-pathnames.lisp (file)

Function: pathname-as-file PATHSPEC

Converts the non-wild pathname designator PATHSPEC to file form.

Package

illogical-pathnames

Source

illogical-pathnames.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   I   L   O  
Index Entry  Section

F
File, Lisp, illogical-pathnames.asd: The illogical-pathnames<dot>asd file
File, Lisp, illogical-pathnames/illogical-pathnames.lisp: The illogical-pathnames/illogical-pathnames<dot>lisp file
File, other, illogical-pathnames/README.txt: The illogical-pathnames/readme<dot>txt file

I
illogical-pathnames.asd: The illogical-pathnames<dot>asd file
illogical-pathnames/illogical-pathnames.lisp: The illogical-pathnames/illogical-pathnames<dot>lisp file
illogical-pathnames/README.txt: The illogical-pathnames/readme<dot>txt file

L
Lisp File, illogical-pathnames.asd: The illogical-pathnames<dot>asd file
Lisp File, illogical-pathnames/illogical-pathnames.lisp: The illogical-pathnames/illogical-pathnames<dot>lisp file

O
Other File, illogical-pathnames/README.txt: The illogical-pathnames/readme<dot>txt file

Jump to:   F   I   L   O  

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

A.2 Functions

Jump to:   (  
C   D   E   F   I   M   N   P   T  
Index Entry  Section

(
(setf illogical-host-translation): Exported functions
(setf illogical-pathname-directory): Exported functions
(setf illogical-pathname-host): Exported functions
(setf illogical-pathname-name): Exported functions
(setf illogical-pathname-type): Exported functions

C
component-present-p: Internal functions
copy-illogical-pathname: Internal functions

D
define-illogical-host: Exported macros
directory-pathname-p: Internal functions
disable-illogical-pathname-syntax: Exported functions

E
enable-illogical-pathname-syntax: Exported functions

F
Function, (setf illogical-host-translation): Exported functions
Function, (setf illogical-pathname-directory): Exported functions
Function, (setf illogical-pathname-host): Exported functions
Function, (setf illogical-pathname-name): Exported functions
Function, (setf illogical-pathname-type): Exported functions
Function, component-present-p: Internal functions
Function, copy-illogical-pathname: Internal functions
Function, directory-pathname-p: Internal functions
Function, disable-illogical-pathname-syntax: Exported functions
Function, enable-illogical-pathname-syntax: Exported functions
Function, illogical-#p-reader: Internal functions
Function, illogical-host-translation: Exported functions
Function, illogical-pathname-directory: Exported functions
Function, illogical-pathname-host: Exported functions
Function, illogical-pathname-name: Exported functions
Function, illogical-pathname-p: Exported functions
Function, illogical-pathname-relative-pathname: Internal functions
Function, illogical-pathname-type: Exported functions
Function, make-illogical-pathname: Exported functions
Function, new-#p-reader: Internal functions
Function, pathname-absolute-p: Internal functions
Function, pathname-as-file: Internal functions
Function, translate-illogical-pathname: Exported functions

I
illogical-#p-reader: Internal functions
illogical-host-translation: Exported functions
illogical-pathname-directory: Exported functions
illogical-pathname-host: Exported functions
illogical-pathname-name: Exported functions
illogical-pathname-p: Exported functions
illogical-pathname-relative-pathname: Internal functions
illogical-pathname-type: Exported functions

M
Macro, define-illogical-host: Exported macros
make-illogical-pathname: Exported functions

N
new-#p-reader: Internal functions

P
pathname-absolute-p: Internal functions
pathname-as-file: Internal functions

T
translate-illogical-pathname: Exported functions

Jump to:   (  
C   D   E   F   I   M   N   P   T  

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

A.3 Variables

Jump to:   *  
D   H   N   S   T  
Index Entry  Section

*
*common-lisp-sharp-p*: Internal special variables
*illogical-hosts*: Internal special variables

D
directory: Exported structures

H
host: Exported structures

N
name: Exported structures

S
Slot, directory: Exported structures
Slot, host: Exported structures
Slot, name: Exported structures
Slot, type: Exported structures
Special Variable, *common-lisp-sharp-p*: Internal special variables
Special Variable, *illogical-hosts*: Internal special variables

T
type: Exported structures

Jump to:   *  
D   H   N   S   T  

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

A.4 Data types

Jump to:   I   P   S   T  
Index Entry  Section

I
illogical-host: Exported types
illogical-pathname: Exported structures
illogical-pathnames: The illogical-pathnames system
illogical-pathnames: The illogical-pathnames package

P
Package, illogical-pathnames: The illogical-pathnames package

S
Structure, illogical-pathname: Exported structures
System, illogical-pathnames: The illogical-pathnames system

T
Type, illogical-host: Exported types

Jump to:   I   P   S   T