Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the illogical-pathnames Reference Manual, version 1.0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Sun May 15 05:02:30 2022 GMT+0.
• Introduction | What illogical-pathnames is all about | |
• Systems | The systems documentation | |
• Files | The files documentation | |
• Packages | The packages documentation | |
• Definitions | The symbols documentation | |
• Indexes | Concepts, functions, variables and data types |
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: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
• The illogical-pathnames system |
Robert Smith <quad@symbo1ics.com>
BSD 3-clause (See illogical-pathnames.lisp)
Mostly filesystem-position-independent pathnames.
1.0.1
illogical-pathnames.asd (file)
Files are sorted by type and then listed depth-first from the systems components trees.
• Lisp files | ||
• Static files |
Next: Static files, Previous: Files, Up: Files [Contents][Index]
• The illogical-pathnames.asd file | ||
• The illogical-pathnames/illogical-pathnames.lisp file |
Next: The illogical-pathnames/illogical-pathnames․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
illogical-pathnames.asd
illogical-pathnames (system)
Previous: The illogical-pathnames․asd file, Up: Lisp files [Contents][Index]
readme.txt (file)
illogical-pathnames (system)
illogical-pathnames.lisp
Previous: Lisp files, Up: Files [Contents][Index]
• The illogical-pathnames/readme.txt file |
Previous: Static files, Up: Static files [Contents][Index]
illogical-pathnames (system)
README.txt
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
• The illogical-pathnames package |
illogical-pathnames.lisp (file)
ipath
common-lisp
Definitions are sorted by export status, category, package, and then by lexicographic order.
• Exported definitions | ||
• Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
• Exported macros | ||
• Exported functions | ||
• Exported structures | ||
• Exported types |
Next: Exported functions, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
Define the illogical host HOST to the absolute directory DIRECTORY.
illogical-pathnames.lisp (file)
Next: Exported structures, Previous: Exported macros, Up: Exported definitions [Contents][Index]
Disable illogical pathname syntax.
illogical-pathnames.lisp (file)
Enable illogical pathname syntax.
#P"..." ; traditional pathname syntax
#P(<illogical-host> (<directory name>*) <filename>?)
illogical-pathnames.lisp (file)
Translate the illogical host ILLOGICAL-HOST to its defined absolute directory.
illogical-pathnames.lisp (file)
(setf illogical-host-translation) (function)
illogical-pathnames.lisp (file)
illogical-host-translation (function)
illogical-pathnames.lisp (file)
illogical-pathnames.lisp (file)
illogical-pathnames.lisp (file)
illogical-pathnames.lisp (file)
illogical-pathnames.lisp (file)
illogical-pathnames.lisp (file)
Translate the illogical pathname ILLOGICAL-PATHNAME to its equivalent absolute pathname.
illogical-pathnames.lisp (file)
Next: Exported types, Previous: Exported functions, Up: Exported definitions [Contents][Index]
illogical-pathnames.lisp (file)
structure-object (structure)
make-load-form (method)
illogical-pathname-host (function)
(setf illogical-pathname-host) (function)
illogical-pathname-directory (function)
(setf illogical-pathname-directory) (function)
illogical-pathname-name (function)
(setf illogical-pathname-name) (function)
illogical-pathname-type (function)
(setf illogical-pathname-type) (function)
Previous: Exported structures, Up: Exported definitions [Contents][Index]
The type of an illogical host object.
illogical-pathnames.lisp (file)
Previous: Exported definitions, Up: Definitions [Contents][Index]
• Internal special variables | ||
• Internal functions |
Next: Internal functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
illogical-pathnames.lisp (file)
Association between ILLOGICAL-HOSTs and their pathname translation.
illogical-pathnames.lisp (file)
Previous: Internal special variables, Up: Internal definitions [Contents][Index]
Helper function for DIRECTORY-PATHNAME-P which checks whether VALUE is neither NIL nor the keyword :UNSPECIFIC.
illogical-pathnames.lisp (file)
illogical-pathnames.lisp (file)
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.
illogical-pathnames.lisp (file)
Reader for illogical pathnames. Returns an illogical pathname.
illogical-pathnames.lisp (file)
Convert the illogical pathname ILLOGICAL-PATHNAME to its representative relative pathname.
illogical-pathnames.lisp (file)
illogical-pathnames.lisp (file)
Returns true if A is an absolute pathname.
This simply tests if A’s directory list starts with :ABSOLUTE
illogical-pathnames.lisp (file)
Converts the non-wild pathname designator PATHSPEC to file form.
illogical-pathnames.lisp (file)
Previous: Definitions, Up: Top [Contents][Index]
• Concept index | ||
• Function index | ||
• Variable index | ||
• Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
Jump to: | F I L S |
---|
Jump to: | F I L S |
---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
Jump to: | (
C D E F I M N P T |
---|
Jump to: | (
C D E F I M N P T |
---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
Jump to: | *
D H N S T |
---|
Jump to: | *
D H N S T |
---|
Previous: Variable index, Up: Indexes [Contents][Index]
Jump to: | I P S T |
---|
Jump to: | I P S T |
---|