User Tools

A PCRE internal error occured. This might be caused by a faulty plugin

====== Function TRANSLATE-PATHNAME ====== ====Syntax==== * **translate-pathname** //source// //from-wildcard// //to-wildcard// ''&key'' → //translated-pathname// ====Arguments and Values==== * //source// - a //[[CL:Glossary:pathname designator]]//. * //from-wildcard// - a //[[CL:Glossary:pathname designator]]//. * //to-wildcard// - a //[[CL:Glossary:pathname designator]]//. * //translated-pathname// - a //[[CL:Glossary:pathname]]//. ====Description==== **translate-pathname** translates //source// (that matches //from-wildcard//) into a corresponding //[[CL:Glossary:pathname]]// that matches //to-wildcard//, and returns the corresponding //[[CL:Glossary:pathname]]//. The resulting //[[CL:Glossary:pathname]]// is //to-wildcard// with each wildcard or missing field replaced by a portion of //source//. A "wildcard field" is a //[[CL:Glossary:pathname]]// component with a value of **'':wild''**, a **'':wild''** element of a //[[CL:Glossary:list]]//-valued directory component, or an //[[CL:Glossary:implementation-defined]]// portion of a component, such as the ''"*"'' in the complex wildcard string ''"foo*bar"'' that some implementations support. An implementation that adds other wildcard features, such as regular expressions, must define how **translate-pathname** extends to those features. A "missing field" is a //[[CL:Glossary:pathname]]// component with a value of **[[CL:Constant Variables:nil]]**. The portion of //source// that is copied into the resulting //[[CL:Glossary:pathname]]// is //[[CL:Glossary:implementation-defined]]//. Typically it is determined by the user interface conventions of the file systems involved. Usually it is the portion of //source// that matches a wildcard field of //from-wildcard// that is in the same position as the wildcard or missing field of //to-wildcard//. If there is no wildcard field in //from-wildcard// at that position, then usually it is the entire corresponding //[[CL:Glossary:pathname]]// component of //source//, or in the case of a //[[CL:Glossary:list]]//-valued directory component, the entire corresponding //[[CL:Glossary:list]]// element. During the copying of a portion of //source// into the resulting //[[CL:Glossary:pathname]]//, additional //[[CL:Glossary:implementation-defined]]// translations of //[[CL:Glossary:case]]// or file naming conventions might occur, especially when //from-wildcard// and //to-wildcard// are for different hosts. It is valid for //source// to be a wild //[[CL:Glossary:pathname]]//; in general this will produce a wild result. It is valid for //from-wildcard// and/or //to-wildcard// to be non-wild //[[CL:Glossary:pathnames]]//. There are no specified keyword arguments for **translate-pathname**, but implementations are permitted to extend it by adding keyword arguments. **translate-pathname** maps customary case in //source// into customary case in the output //[[CL:Glossary:pathname]]//. ====Examples==== The results of the following five forms are all //[[CL:Glossary:implementation-dependent]]//. The second item in particular is shown with multiple results just to emphasize one of many particular variations which commonly occurs. <blockquote> ([[CL:Functions:pathname-name]] (translate-pathname "foobar" "foo*" "*baz")) <r>"barbaz" </r> ([[CL:Functions:pathname-name]] (translate-pathname "foobar" "foo*" "*")) <r>"foobar"</r> <r>//or// "bar" </r> ([[CL:Functions:pathname-name]] (translate-pathname "foobar" "*" "foo*")) <r>"foofoobar" </r> ([[CL:Functions:pathname-name]] (translate-pathname "bar" "*" "foo*")) <r>"foobar" </r> ([[CL:Functions:pathname-name]] (translate-pathname "foobar" "foo*" "baz*")) <r>"bazbar"</r> ([[CL:Macros:defun]] translate-logical-pathname-1 (pathname rules) ([[CL:Special Operators:let]] ((rule ([[CL:Functions:assoc]] pathname rules :test #'[[CL:Functions:pathname-match-p]]))) ([[CL:Macros:unless]] rule ([[CL:Functions:error]] "No translation rule for ~A" pathname)) (translate-pathname pathname ([[CL:Functions:first]] rule) ([[CL:Functions:second]] rule)))) <r>TRANSLATE-LOGICAL-PATHNAME-1</r> (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/*/"))) <r>#P"MY-UNIX:/lib/foo/basic.l"</r> </blockquote> This example assumes one particular set of wildcard conventions. Not all file systems will run this example exactly as written. <blockquote> ([[CL:Macros:defun]] rename-files (from to) ([[CL:Macros:dolist]] (file ([[CL:Functions:directory]] from)) ([[CL:Functions:rename-file]] file (translate-pathname file from to)))) <r>RENAME-FILES</r> (rename-files "/usr/me/*.lisp" "/dev/her/*.l") <r>NIL ;;; Renames /usr/me/init.lisp to /dev/her/init.l </r> (rename-files "/usr/me/pcl*/*" "/sys/pcl/*/") <r>NIL ;;; 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 </r> (rename-files "/usr/me/pcl*/*" "/sys/library/*/") <r>NIL ;;; 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 </r> (rename-files "/usr/me/foo.bar" "/usr/me2/") <r>NIL ;;; Renames /usr/me/foo.bar to /usr/me2/foo.bar </r> (rename-files "/usr/joe/*-recipes.text" "/usr/jim/cookbook/joe's-*-rec.text") <r>NIL ;;; 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</r> </blockquote> ====Affected By==== None. ====Exceptional Situations==== If any of //source//, //from-wildcard//, or //to-wildcard// is not a //[[CL:Glossary:pathname]]//, a //[[CL:Glossary:string]]//, or a //[[CL:Glossary:stream associated with a file]]// an error of type **[[CL:Types:type-error]]** is signaled. ''([[CL:Functions:pathname-match-p]] //source from-wildcard//)'' must be true or an error of type **[[CL:Types:error]]** is signaled. ====See Also==== * **[[CL:Functions:namestring|Function NAMESTRING]]** * **[[CL:Functions:pathname-host|Function PATHNAME-HOST]]** * **[[CL:Types:pathname|System Class PATHNAME]]** * **[[CL:Types:logical-pathname|System Class LOGICAL-PATHNAME]]** * {\secref\FileSystemConcepts} * {\secref\PathnamesAsFilenames} ====Notes==== The exact behavior of **translate-pathname** 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. The following is an implementation guideline. One file system performs this operation by examining each piece of the three //[[CL:Glossary:pathnames]]// in turn, where a piece is a //[[CL:Glossary:pathname]]// component or a //[[CL:Glossary:list]]// element of a structured component such as a hierarchical directory. Hierarchical directory elements in //from-wildcard// and //to-wildcard// are matched by whether they are wildcards, not by depth in the directory hierarchy. If the piece in //to-wildcard// is present and not wild, it is copied into the result. If the piece in //to-wildcard// is **'':wild''** or **[[CL:Constant Variables:nil]]**, the piece in //source// is copied into the result. Otherwise, the piece in //to-wildcard// might be a complex wildcard such as ''"foo*bar"'' and the piece in //from-wildcard// should be wild; the portion of the piece in //source// that matches the wildcard portion of the piece in //from-wildcard// replaces the wildcard portion of the piece in //to-wildcard// and the value produced is used in the result. \issue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR} \issue{PATHNAME-WILD:NEW-FUNCTIONS} \issue{PATHNAME-COMPONENT-CASE:KEYWORD-ARGUMENT} \issue{JUN90-TRIVIAL-ISSUES:5} \issue{PATHNAME-LOGICAL:ADD}