User Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

cl:functions:parse-namestring [2019/11/11 05:00]
cl:functions:parse-namestring [2019/12/15 08:00] (current)
Line 1: Line 1:
 +====== Function PARSE-NAMESTRING ======
 +
 +====Syntax====
 +  * **parse-namestring** //thing// ''&​optional''​ //host// //​default-pathname//​ ''&​key''​ //start// //end// //​junk-allowed//​ → //pathname, position//
 +
 +====Arguments and Values====
 +  * //thing// - a //​[[CL:​Glossary:​string]]//,​ a //​[[CL:​Glossary:​pathname]]//,​ or a //​[[CL:​Glossary:​stream associated with a file]]//.
 +  * //host// - a //​[[CL:​Glossary:​valid pathname host]]//, a //​[[CL:​Glossary:​logical host]]//, or **[[CL:​Constant Variables:​nil]]**.
 +  * //​default-pathname//​ - a //​[[CL:​Glossary:​pathname designator]]//​. The default is the //​[[CL:​Glossary:​value]]//​ of **[[CL:​Variables:​star-default-pathname-defaults-star|*default-pathname-defaults*]]**.
 +  * //start//, //end// - //​[[CL:​Glossary:​bounding index designators]]//​ of //thing//. The defaults for //start// and //end/are ''​0''​ and **[[CL:​Constant Variables:​nil]]**,​ respectively.
 +  * //​junk-allowed//​ - a //​[[CL:​Glossary:​generalized boolean]]//​. The default is //​[[CL:​Glossary:​false]]//​.
 +  * //​pathname//​ - a //​[[CL:​Glossary:​pathname]]//,​ or **[[CL:​Constant Variables:​nil]]**.
 +  * //​position//​ - a //​[[CL:​Glossary:​bounding index designator]]//​ for //thing//.
 +
 +====Description====
 +Converts //thing// into a //​[[CL:​Glossary:​pathname]]//​.
 +
 +The //host// supplies a host name with respect to which the parsing occurs.
 +
 +If //thing// is a //​[[CL:​Glossary:​stream associated with a file]]//, processing proceeds as if the //​[[CL:​Glossary:​pathname]]//​ used to open that //​[[CL:​Glossary:​file]]//​ had been supplied instead.
 +
 +If //thing// is a //​[[CL:​Glossary:​pathname]]//,​ the //host// and the host component of //thing// are compared.
 +
 +If they match, two values are immediately returned: //thing// and //start//; otherwise (if they do not match), an error is signaled.
 +
 +Otherwise (if //thing// is a //​[[CL:​Glossary:​string]]//​),​ **[[CL:​Functions:​parse-namestring]]** parses the name of a //​[[CL:​Glossary:​file]]//​ within the substring of //thing// bounded by //start// and //end//.
 +
 +If //thing// is a //​[[CL:​Glossary:​string]]//​ then the substring of //thing// //​[[CL:​Glossary:​bounded]]//​ by //start// and //end// is parsed into a //​[[CL:​Glossary:​pathname]]//​ as follows:
 +
 +  * If //host// is a //​[[CL:​Glossary:​logical host]]// then //thing// is parsed as a //​[[CL:​Glossary:​logical pathname]]//​ //​[[CL:​Glossary:​namestring]]//​ on the //host//.
 +  * If //host// is **[[CL:​Constant Variables:​nil]]** and //thing// is a syntactically valid //​[[CL:​Glossary:​logical pathname]]//​ //​[[CL:​Glossary:​namestring]]//​ containing an explicit host, then it is parsed as a //​[[CL:​Glossary:​logical pathname]]//​ //​[[CL:​Glossary:​namestring]]//​.
 +  * If //host// is **[[CL:​Constant Variables:​nil]]**,​ //​default-pathname//​ is a //​[[CL:​Glossary:​logical pathname]]//,​ and //thing// is a syntactically valid //​[[CL:​Glossary:​logical pathname]]//​ //​[[CL:​Glossary:​namestring]]//​ without an explicit host, then it is parsed as a //​[[CL:​Glossary:​logical pathname]]//​ //​[[CL:​Glossary:​namestring]]//​ on the host that is the host component of //​default-pathname//​.
 +  * Otherwise, the parsing of //thing// is //​[[CL:​Glossary:​implementation-defined]]//​.
 +
 +In the first of these cases, the host portion of the //​[[CL:​Glossary:​logical pathname]]//​ namestring and its following //​[[CL:​Glossary:​colon]]//​ are optional.
 +
 +If the host portion of the namestring and //host// are both present and do not match, an error is signaled.
 +
 +If //​junk-allowed//​ is //​[[CL:​Glossary:​true]]//,​ then the //​[[CL:​Glossary:​primary value]]// is the //​[[CL:​Glossary:​pathname]]//​ parsed or, if no syntactically correct //​[[CL:​Glossary:​pathname]]//​ was seen, **[[CL:​Constant Variables:​nil]]**.
 +
 +If //​junk-allowed//​ is //​[[CL:​Glossary:​false]]//,​ then the entire substring is scanned, and the //​[[CL:​Glossary:​primary value]]// is the //​[[CL:​Glossary:​pathname]]//​ parsed.
 +
 +In either case, the //​[[CL:​Glossary:​secondary value]]// is the index into //thing// of the delimiter that terminated the parse, or the index beyond the substring if the parse terminated at the end of the substring (as will always be the case if //​junk-allowed//​ is //​[[CL:​Glossary:​false]]//​).
 +
 +Parsing a //​[[CL:​Glossary:​null]]//​ //​[[CL:​Glossary:​string]]//​ always succeeds, producing a //​[[CL:​Glossary:​pathname]]//​ with all components (except the host) equal to **[[CL:​Constant Variables:​nil]]**.
 +
 +If //thing// contains an explicit host name and no explicit device name, then it is //​[[CL:​Glossary:​implementation-defined]]//​ whether **[[CL:​Functions:​parse-namestring]]** will supply the standard default device for that host as the device component of the resulting //​[[CL:​Glossary:​pathname]]//​.
 +
 +====Examples====
 +<​blockquote>​
 +([[CL:​Macros:​defparameter]] *q* (parse-namestring "​test"​)) <​r>​*Q*</​r>​
 +*q* 
 +<​r>#​S(PATHNAME :HOST [[CL:​Constant Variables:​nil|NIL]] :DEVICE [[CL:​Constant Variables:​nil|NIL]] :DIRECTORY [[CL:​Constant Variables:​nil|NIL]] ​
 +            :NAME "​test"​ :TYPE [[CL:​Constant Variables:​nil|NIL]] :VERSION [[CL:​Constant Variables:​nil|NIL]]) </r>
 +([[CL:​Functions:​pathnamep]] *q*) <​r>//​[[CL:​Glossary:​true]]//​ </r>
 +(parse-namestring "​test"​) ​
 +<​r>#​S(PATHNAME :HOST [[CL:​Constant Variables:​nil|NIL]] :DEVICE [[CL:​Constant Variables:​nil|NIL]] :DIRECTORY [[CL:​Constant Variables:​nil|NIL]] ​
 +            :NAME "​test"​ :TYPE [[CL:​Constant Variables:​nil|NIL]] :VERSION [[CL:​Constant Variables:​nil|NIL]])
 +4 </r>
 +([[CL:​Macros:​defparameter]] *s* (open //xxx//)) <​r>#<​Input File Stream...>​ </r>
 +(parse-namestring *s*) 
 +<​r>#​S(PATHNAME :HOST [[CL:​Constant Variables:​nil|NIL]] :DEVICE [[CL:​Constant Variables:​nil|NIL]] :DIRECTORY [[CL:​Constant Variables:​nil|NIL]] ​
 +            :NAME //xxx// :TYPE [[CL:​Constant Variables:​nil|NIL]] :VERSION [[CL:​Constant Variables:​nil|NIL]])
 +0 </r>
 +(parse-namestring "​test"​ [[CL:​Constant Variables:​nil]] [[CL:​Constant Variables:​nil]] :start 2 :end 4) <​r>#​S(PATHNAME ...)
 +15 </r>
 +(parse-namestring "​foo.lisp"​) <​r>#​P"​foo.lisp"​ </r>
 +</​blockquote>​
 +
 +====Affected By====
 +None.
 +
 +====Exceptional Situations====
 +If //​junk-allowed//​ is //​[[CL:​Glossary:​false]]//,​ an error of type **[[CL:​Types:​parse-error]]** is signaled if //thing// does not consist entirely of the representation of a //​[[CL:​Glossary:​pathname]]//,​ possibly surrounded on either side by //​[[CL:​Glossary:​whitespace]]//​ characters if that is appropriate to the cultural conventions of the implementation.
 +
 +If //host// is supplied and not **[[CL:​Constant Variables:​nil]]**,​ and //thing// contains a manifest host name, an error of type **[[CL:​Types:​error]]** is signaled if the hosts do not match.
 +
 +If //thing// is a //​[[CL:​Glossary:​logical pathname]]//​ namestring and if the host portion of the namestring and //host// are both present and do not match, an error of type **[[CL:​Types:​error]]** is signaled.
 +
 +====See Also====
 +  * **[[CL:​Types:​pathname|System Class PATHNAME]]**
 +  * **[[CL:​Types:​logical-pathname|System Class LOGICAL-PATHNAME]]**
 +  * {\secref\FileSystemConcepts}
 +  * {\secref\UnspecificComponent}
 +  * {\secref\PathnamesAsFilenames}
 +
 +====Notes====
 +None.
 +
 +\issue{PATHNAME-PRINT-READ:​SHARPSIGN-P} \issue{PATHNAME-LOGICAL:​ADD} \issue{PATHNAME-LOGICAL:​ADD} \issue{FILE-OPEN-ERROR:​SIGNAL-FILE-ERROR} \issue{PATHNAME-SYMBOL} \issue{PATHNAME-LOGICAL:​ADD} \issue{PATHNAME-LOGICAL:​ADD} \issue{PATHNAME-UNSPECIFIC-COMPONENT:​NEW-TOKEN} \issue{SUBSEQ-OUT-OF-BOUNDS} \issue{RANGE-OF-START-AND-END-PARAMETERS:​INTEGER-AND-INTEGER-NIL} \issue{PATHNAME-STREAM} \issue{PATHNAME-SYMBOL} \issue{PATHNAME-LOGICAL:​ADD} \issue{PATHNAME-HOST-PARSING:​RECOGNIZE-LOGICAL-HOST-NAMES}