106 lines
12 KiB
HTML
106 lines
12 KiB
HTML
<!-- Common Lisp HyperSpec (TM), version 7.0 generated by Kent M. Pitman on Mon, 11-Apr-2005 2:31am EDT -->
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>CLHS: Function TRANSLATE-PATHNAME</TITLE>
|
|
<LINK HREF="../Data/clhs.css" REL="stylesheet" TYPE="text/css" />
|
|
<META HTTP-EQUIV="Author" CONTENT="Kent M. Pitman">
|
|
<META HTTP-EQUIV="Organization" CONTENT="LispWorks Ltd.">
|
|
<LINK REL=TOP HREF="../Front/index.htm">
|
|
<LINK REL=COPYRIGHT HREF="../Front/Help.htm#Legal">
|
|
<LINK REL=DISCLAIMER HREF="../Front/Help.htm#Disclaimer">
|
|
<LINK REL=PREV HREF="f_tr_log.htm">
|
|
<LINK REL=UP HREF="c_filena.htm">
|
|
<LINK REL=NEXT HREF="f_merge_.htm">
|
|
</HEAD>
|
|
<BODY>
|
|
<H1><A REV=MADE HREF="http://www.lispworks.com/"><IMG WIDTH=80 HEIGHT=65 ALT="[LISPWORKS]" SRC="../Graphics/LWSmall.gif" ALIGN=Bottom></A><A REL=TOP HREF="../Front/index.htm"><IMG WIDTH=237 HEIGHT=65 ALT="[Common Lisp HyperSpec (TM)]" SRC="../Graphics/CLHS_Sm.gif" ALIGN=Bottom></A> <A REL=PREV HREF="f_tr_log.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Previous]" SRC="../Graphics/Prev.gif" ALIGN=Bottom></A><A REL=UP HREF="c_filena.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Up]" SRC="../Graphics/Up.gif" ALIGN=Bottom></A><A REL=NEXT HREF="f_merge_.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Next]" SRC="../Graphics/Next.gif" ALIGN=Bottom></A></H1>
|
|
|
|
<HR>
|
|
|
|
<A NAME="translate-pathname"><I>Function</I> <B>TRANSLATE-PATHNAME</B></A> <P>
|
|
<P>
|
|
<P><B>Syntax:</B><P>
|
|
<P>
|
|
|
|
<B>translate-pathname</B> <I>source from-wildcard to-wildcard <TT>&key</TT></I><P> => <I>translated-pathname</I><P>
|
|
<P>
|
|
<P><B>Arguments and Values:</B><P>
|
|
<P>
|
|
<I>source</I>---a <A REL=DEFINITION HREF="26_glo_p.htm#pathname_designator"><I>pathname designator</I></A>. <P>
|
|
<I>from-wildcard</I>---a <A REL=DEFINITION HREF="26_glo_p.htm#pathname_designator"><I>pathname designator</I></A>. <P>
|
|
<I>to-wildcard</I>---a <A REL=DEFINITION HREF="26_glo_p.htm#pathname_designator"><I>pathname designator</I></A>. <P>
|
|
<I>translated-pathname</I>---a <A REL=DEFINITION HREF="26_glo_p.htm#pathname"><I>pathname</I></A>. <P>
|
|
<P><B>Description:</B><P>
|
|
<P>
|
|
<A REL=DEFINITION HREF="#translate-pathname"><B>translate-pathname</B></A> translates <I>source</I> (that matches <I>from-wildcard</I>) into a corresponding <A REL=DEFINITION HREF="26_glo_p.htm#pathname"><I>pathname</I></A> that matches <I>to-wildcard</I>, and returns the corresponding <A REL=DEFINITION HREF="26_glo_p.htm#pathname"><I>pathname</I></A>. <P>
|
|
The resulting <A REL=DEFINITION HREF="26_glo_p.htm#pathname"><I>pathname</I></A> is <I>to-wildcard</I> with each wildcard or missing field replaced by a portion of <I>source</I>. A ``wildcard field'' is a <A REL=DEFINITION HREF="26_glo_p.htm#pathname"><I>pathname</I></A> component with a value of <TT>:wild</TT>, a <TT>:wild</TT> element of a <A REL=DEFINITION HREF="26_glo_l.htm#list"><I>list</I></A>-valued directory component, or an <A REL=DEFINITION HREF="26_glo_i.htm#implementation-defined"><I>implementation-defined</I></A> portion of a component, such as the <TT>"*"</TT> in the complex wildcard string <TT>"foo*bar"</TT> that some implementations support. An implementation that adds other wildcard features, such as regular expressions, must define how <A REL=DEFINITION HREF="#translate-pathname"><B>translate-pathname</B></A> extends to those features. A ``missing field'' is a <A REL=DEFINITION HREF="26_glo_p.htm#pathname"><I>pathname</I></A> component with a value of <A REL=DEFINITION HREF="a_nil.htm#nil"><B>nil</B></A>. <P>
|
|
The portion of <I>source</I> that is copied into the resulting <A REL=DEFINITION HREF="26_glo_p.htm#pathname"><I>pathname</I></A> is <A REL=DEFINITION HREF="26_glo_i.htm#implementation-defined"><I>implementation-defined</I></A>. Typically it is determined by the user interface conventions of the file systems involved. Usually it is the portion of <I>source</I> that matches a wildcard field of <I>from-wildcard</I> that is in the same position as the wildcard or missing field of <I>to-wildcard</I>. If there is no wildcard field in <I>from-wildcard</I> at that position, then usually it is the entire corresponding <A REL=DEFINITION HREF="26_glo_p.htm#pathname"><I>pathname</I></A> component of <I>source</I>, or in the case of a <A REL=DEFINITION HREF="26_glo_l.htm#list"><I>list</I></A>-valued directory component, the entire corresponding <A REL=DEFINITION HREF="26_glo_l.htm#list"><I>list</I></A> element. <P>
|
|
During the copying of a portion of <I>source</I> into the resulting <A REL=DEFINITION HREF="26_glo_p.htm#pathname"><I>pathname</I></A>, additional <A REL=DEFINITION HREF="26_glo_i.htm#implementation-defined"><I>implementation-defined</I></A> translations of <A REL=DEFINITION HREF="26_glo_c.htm#case"><I>case</I></A> or file naming conventions might occur, especially when <I>from-wildcard</I> and <I>to-wildcard</I> are for different hosts. <P>
|
|
It is valid for <I>source</I> to be a wild <A REL=DEFINITION HREF="26_glo_p.htm#pathname"><I>pathname</I></A>; in general this will produce a wild result. It is valid for <I>from-wildcard</I> and/or <I>to-wildcard</I> to be non-wild <A REL=DEFINITION HREF="26_glo_p.htm#pathname"><I>pathnames</I></A>. <P>
|
|
There are no specified keyword arguments for <A REL=DEFINITION HREF="#translate-pathname"><B>translate-pathname</B></A>, but implementations are permitted to extend it by adding keyword arguments. <P>
|
|
<A REL=DEFINITION HREF="#translate-pathname"><B>translate-pathname</B></A> maps customary case in <I>source</I> into customary case in the output <A REL=DEFINITION HREF="26_glo_p.htm#pathname"><I>pathname</I></A>. <P>
|
|
<P><B>Examples:</B><P>
|
|
<P>
|
|
<PRE>
|
|
;; The results of the following five forms are all implementation-dependent.
|
|
;; The second item in particular is shown with multiple results just to
|
|
;; emphasize one of many particular variations which commonly occurs.
|
|
(pathname-name (translate-pathname "foobar" "foo*" "*baz")) => "barbaz"
|
|
(pathname-name (translate-pathname "foobar" "foo*" "*"))
|
|
=> "foobar"
|
|
OR=> "bar"
|
|
(pathname-name (translate-pathname "foobar" "*" "foo*")) => "foofoobar"
|
|
(pathname-name (translate-pathname "bar" "*" "foo*")) => "foobar"
|
|
(pathname-name (translate-pathname "foobar" "foo*" "baz*")) => "bazbar"
|
|
|
|
(defun translate-logical-pathname-1 (pathname rules)
|
|
(let ((rule (assoc pathname rules :test #'pathname-match-p)))
|
|
(unless rule (error "No translation rule for ~A" pathname))
|
|
(translate-pathname pathname (first rule) (second rule))))
|
|
(translate-logical-pathname-1 "FOO:CODE;BASIC.LISP"
|
|
'(("FOO:DOCUMENTATION;" "MY-UNIX:/doc/foo/")
|
|
("FOO:CODE;" "MY-UNIX:/lib/foo/")
|
|
("FOO:PATCHES;*;" "MY-UNIX:/lib/foo/patch/*/")))
|
|
=> #P"MY-UNIX:/lib/foo/basic.l"
|
|
|
|
;;;This example assumes one particular set of wildcard conventions
|
|
;;;Not all file systems will run this example exactly as written
|
|
(defun rename-files (from to)
|
|
(dolist (file (directory from))
|
|
(rename-file file (translate-pathname file from to))))
|
|
(rename-files "/usr/me/*.lisp" "/dev/her/*.l")
|
|
;Renames /usr/me/init.lisp to /dev/her/init.l
|
|
(rename-files "/usr/me/pcl*/*" "/sys/pcl/*/")
|
|
;Renames /usr/me/pcl-5-may/low.lisp to /sys/pcl/pcl-5-may/low.lisp
|
|
;In some file systems the result might be /sys/pcl/5-may/low.lisp
|
|
(rename-files "/usr/me/pcl*/*" "/sys/library/*/")
|
|
;Renames /usr/me/pcl-5-may/low.lisp to /sys/library/pcl-5-may/low.lisp
|
|
;In some file systems the result might be /sys/library/5-may/low.lisp
|
|
(rename-files "/usr/me/foo.bar" "/usr/me2/")
|
|
;Renames /usr/me/foo.bar to /usr/me2/foo.bar
|
|
(rename-files "/usr/joe/*-recipes.text" "/usr/jim/cookbook/joe's-*-rec.text")
|
|
;Renames /usr/joe/lamb-recipes.text to /usr/jim/cookbook/joe's-lamb-rec.text
|
|
;Renames /usr/joe/pork-recipes.text to /usr/jim/cookbook/joe's-pork-rec.text
|
|
;Renames /usr/joe/veg-recipes.text to /usr/jim/cookbook/joe's-veg-rec.text
|
|
</PRE>
|
|
</TT> <P>
|
|
<P><B>Affected By:</B> None.
|
|
<P>
|
|
<P><B>Exceptional Situations:</B><P>
|
|
<P>
|
|
If any of <I>source</I>, <I>from-wildcard</I>, or <I>to-wildcard</I> is not a <A REL=DEFINITION HREF="26_glo_p.htm#pathname"><I>pathname</I></A>, a <A REL=DEFINITION HREF="26_glo_s.htm#string"><I>string</I></A>, or a <A REL=DEFINITION HREF="26_glo_s.htm#stream_associated_with_a_file"><I>stream associated with a file</I></A> an error of <A REL=DEFINITION HREF="26_glo_t.htm#type"><I>type</I></A> <A REL=DEFINITION HREF="e_tp_err.htm#type-error"><B>type-error</B></A> is signaled. <P>
|
|
<TT>(pathname-match-p </TT><I>source from-wildcard</I><TT>)</TT> must be true or an error of <A REL=DEFINITION HREF="26_glo_t.htm#type"><I>type</I></A> <A REL=DEFINITION HREF="e_error.htm#error"><B>error</B></A> is signaled. <P>
|
|
<P><B>See Also:</B><P>
|
|
<P>
|
|
<A REL=DEFINITION HREF="f_namest.htm#namestring"><B>namestring</B></A>, <A REL=DEFINITION HREF="f_pn_hos.htm#pathname-host"><B>pathname-host</B></A>, <A REL=DEFINITION HREF="t_pn.htm#pathname"><B>pathname</B></A>, <A REL=DEFINITION HREF="t_logica.htm#logical-pathname"><B>logical-pathname</B></A>, <A REL=CHILD HREF="20_a.htm">Section 20.1 (File System Concepts)</A>, <A REL=CHILD HREF="19_ab.htm">Section 19.1.2 (Pathnames as Filenames)</A> <P>
|
|
<P><B>Notes:</B><P>
|
|
<P>
|
|
The exact behavior of <A REL=DEFINITION HREF="#translate-pathname"><B>translate-pathname</B></A> cannot be dictated by the Common Lisp language and must be allowed to vary, depending on the user interface conventions of the file systems involved. <P>
|
|
The following is an implementation guideline. One file system performs this operation by examining each piece of the three <A REL=DEFINITION HREF="26_glo_p.htm#pathname"><I>pathnames</I></A> in turn, where a piece is a <A REL=DEFINITION HREF="26_glo_p.htm#pathname"><I>pathname</I></A> component or a <A REL=DEFINITION HREF="26_glo_l.htm#list"><I>list</I></A> element of a structured component such as a hierarchical directory. Hierarchical directory elements in <I>from-wildcard</I> and <I>to-wildcard</I> are matched by whether they are wildcards, not by depth in the directory hierarchy. If the piece in <I>to-wildcard</I> is present and not wild, it is copied into the result. If the piece in <I>to-wildcard</I> is <TT>:wild</TT> or <A REL=DEFINITION HREF="a_nil.htm#nil"><B>nil</B></A>, the piece in <I>source</I> is copied into the result. Otherwise, the piece in <I>to-wildcard</I> might be a complex wildcard such as <TT>"foo*bar"</TT> and the piece in <I>from-wildcard</I> should be wild; the portion of the piece in <I>source</I> that matches the wildcard portion of the piece in <I>from-wildcard</I> replaces the wildcard portion of the piece in <I>to-wildcard</I> and the value produced is used in the result. <P>
|
|
<P><HR>The following <A REL=META HREF="../Front/X3J13Iss.htm">X3J13 cleanup issues</A>, <I>not part of the specification</I>, apply to this section:<P><UL><LI> <A REL=CHILD HREF="../Issues/iss157.htm">FILE-OPEN-ERROR:SIGNAL-FILE-ERROR</A><LI> <A REL=CHILD HREF="../Issues/iss259.htm">PATHNAME-LOGICAL:ADD</A><LI> <A REL=CHILD HREF="../Issues/iss206.htm">JUN90-TRIVIAL-ISSUES:5</A><LI> <A REL=CHILD HREF="../Issues/iss256.htm">PATHNAME-COMPONENT-CASE:KEYWORD-ARGUMENT</A><LI> <A REL=CHILD HREF="../Issues/iss267.htm">PATHNAME-WILD:NEW-FUNCTIONS</A><P></UL><HR>
|
|
|
|
<A REL=NAVIGATOR HREF="../Front/StartPts.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Starting Points]" SRC="../Graphics/StartPts.gif" ALIGN=Bottom></A><A REL=TOC HREF="../Front/Contents.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Contents]" SRC="../Graphics/Contents.gif" ALIGN=Bottom></A><A REL=INDEX HREF="../Front/X_Master.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Index]" SRC="../Graphics/Index.gif" ALIGN=Bottom></A><A REL=INDEX HREF="../Front/X_Symbol.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Symbols]" SRC="../Graphics/Symbols.gif" ALIGN=Bottom></A><A REL=GLOSSARY HREF="../Body/26_a.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Glossary]" SRC="../Graphics/Glossary.gif" ALIGN=Bottom></A><A HREF="../Front/X3J13Iss.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Issues]" SRC="../Graphics/Issues.gif" ALIGN=Bottom></A><BR>
|
|
|
|
<A REL=COPYRIGHT HREF="../Front/Help.htm#Legal"><I>Copyright 1996-2005, LispWorks Ltd. All rights reserved.</I></A><P>
|
|
</BODY>
|
|
</HTML>
|