Diff of /ansi_filenames.xml [000000] .. [bbf6a2] Maximize Restore

  Switch to unified view

a b/ansi_filenames.xml
1
<?xml version="1.0" encoding="utf-8"?>
2
<!DOCTYPE book [
3
<!ENTITY % eclent SYSTEM "ecl.ent">
4
%eclent;
5
]>
6
<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
7
<chapter xml:id="ansi.filenames">
8
 <title>Filenames</title>
9
10
 <section xml:id="ansi.filenames.syntax">
11
  <title>Syntax</title>
12
  <para>A pathname in the file system of Common-Lisp consists of six
13
  elements: host, device, directory, name, type and version. Pathnames are
14
  read and printed using the <literal>#P</literal> reader macro followed by
15
  the namestring. A namestring is a string which represents a pathname. The
16
  syntax of namestrings for logical pathnames is well explained in the &ANSI;
17
  and it can be roughly summarized as follows:
18
19
  <synopsis><literal><optional><replaceable>hostname</replaceable>:</optional><optional>;</optional><optional><replaceable>directory-item</replaceable>;</optional><superscript>0 or more</superscript><optional><replaceable>name</replaceable></optional><optional>.<replaceable>type</replaceable><optional>.<replaceable>version</replaceable></optional></optional></literal>
20
  <replaceable>hostname</replaceable> = <replaceable>word</replaceable>
21
  <replaceable>directory-item</replaceable> = <replaceable>wildcard-word</replaceable>
22
  <replaceable>type</replaceable>, <replaceable>name</replaceable> = <replaceable>wildcard-word</replaceable> without dots</synopsis>
23
24
  Here, <replaceable>wildcard-word</replaceable> is a sequence of any
25
  character excluding <literal>#\Null</literal> and
26
  dots. <replaceable>word</replaceable> is like a
27
  <replaceable>wildcard-word</replaceable> but asterisks are excluded.</para>
28
29
  <para>The way &ECL; parses a namestring is by first looking for the
30
  <replaceable>hostname</replaceable> component in the previous template. If
31
  it is found and it corresponds to a previously defined logical hostname, it
32
  assumes that the namestring corresponds to a logical pathname. If
33
  <replaceable>hostname</replaceable> is not found or it is not a logical
34
  hostname, then &ECL; tries the physical pathname syntax
35
36
  <synopsis><literal><optional><replaceable>device</replaceable>:</optional><optional><optional>//<replaceable>hostname</replaceable></optional>/</optional><optional><replaceable>directory-item</replaceable>/</optional><superscript>0 or more</superscript><optional><replaceable>name</replaceable></optional><optional>.<replaceable>type</replaceable></optional></literal>
37
  <replaceable>device</replaceable>, <replaceable>hostname</replaceable> = <replaceable>word</replaceable>
38
  <replaceable>directory-item</replaceable> = <replaceable>wildcard-word</replaceable>
39
  <replaceable>type</replaceable> = <replaceable>wildcard-word</replaceable> without dots
40
  <replaceable>name</replaceable> = <optional>.</optional><replaceable>wildcard-word</replaceable></synopsis>
41
42
  If this syntax also fails, then the namestring is not a valid pathname
43
  string and a <type>parse-error</type> will be signalled.</para>
44
45
  <para>It is important to remark that in &ECL;, all physical namestrings
46
  result into pathnames with a version equal to
47
  <literal>:NEWEST</literal>. Pathnames which are not logical and have any
48
  other version (i. e. <literal>NIL</literal> or a number), cannot be printed
49
  readably, but can produce a valid namestring which results of ignoring the
50
  version.</para>
51
52
  <para>Finally, an important rule applies to physical namestrings: if a
53
  namestring contains one or more periods `.', the last period separates the
54
  namestring into the file name and the filetype. However, a namestring with a
55
  single leading period results in a name with a period in it. This is for
56
  compatibility with Unix filenames such as <filename>.bashrc</filename>, where
57
  the leading period indicates that the file is hidden.</para>
58
59
  <para>The previous rule has in important consequence, because it means that
60
  if you want to create a pathname without a name, you have to do it
61
  explicitely. In other words, <literal>".*"</literal> is equivalent to
62
  <code>(MAKE-PATHNAME :NAME ".*" :TYPE NIL)</code>, while <code>(MAKE-PATHNAME
63
  :NAME NIL :TYPE :WILD)</code> creates a pathname whose type is a
64
  wildcard.</para>
65
66
  <para>The following table illustrates how the physical pathnames work with
67
  practical examples.</para>
68
  <table>
69
   <title>Examples of physical namestrings</title>
70
   <tgroup cols="3">
71
    <thead>
72
     <row><entry>Namestring</entry>
73
     <entry>Name</entry>
74
     <entry>Type</entry>
75
     <entry>Directory</entry>
76
     <entry>Device</entry>
77
     </row>
78
    </thead>
79
    <tbody>
80
     <row>
81
      <entry>"foo.lsp"</entry>
82
      <entry>"foo"</entry>
83
      <entry>"lsp"</entry>
84
      <entry>NIL</entry>
85
      <entry>NIL</entry>
86
     </row>
87
     <row>
88
      <entry>".bashrc"</entry>
89
      <entry>".bashrc"</entry>
90
      <entry>NIL</entry>
91
      <entry>NIL</entry>
92
      <entry>NIL</entry>
93
     </row>
94
     <row>
95
      <entry>".ecl.lsp"</entry>
96
      <entry>".ecl"</entry>
97
      <entry>"lsp"</entry>
98
      <entry>NIL</entry>
99
      <entry>NIL</entry>
100
     </row>
101
     <row>
102
      <entry>"foo.*"</entry>
103
      <entry>"foo"</entry>
104
      <entry>:WILD</entry>
105
      <entry>NIL</entry>
106
      <entry>NIL</entry>
107
     </row>
108
     <row>
109
      <entry>"*.*"</entry>
110
      <entry>:WILD</entry>
111
      <entry>:WILD</entry>
112
      <entry>NIL</entry>
113
      <entry>NIL</entry>
114
     </row>
115
     <row>
116
      <entry>"ecl/build/bare.lsp"</entry>
117
      <entry>"bare"</entry>
118
      <entry>"lsp"</entry>
119
      <entry>(:relative "ecl" "build")</entry>
120
      <entry>NIL</entry>
121
     </row>
122
     <row>
123
      <entry>"ecl/build/"</entry>
124
      <entry>NIL</entry>
125
      <entry>NIL</entry>
126
      <entry>(:relative "ecl" "build")</entry>
127
      <entry>NIL</entry>
128
     </row>
129
     <row>
130
      <entry>"../../ecl/build/"</entry>
131
      <entry>NIL</entry>
132
      <entry>NIL</entry>
133
      <entry>(:relative :up :up "ecl" "build")</entry>
134
      <entry>NIL</entry>
135
     </row>
136
     <row>
137
      <entry>"/etc/"</entry>
138
      <entry>NIL</entry>
139
      <entry>NIL</entry>
140
      <entry>(:absolute "etc")</entry>
141
      <entry>NIL</entry>
142
     </row>
143
     <row>
144
      <entry>"C:/etc/"</entry>
145
      <entry>NIL</entry>
146
      <entry>NIL</entry>
147
      <entry>(:absolute "etc")</entry>
148
      <entry>"C"</entry>
149
     </row>
150
     <row>
151
      <entry>".*"</entry>
152
      <entry>".*"</entry>
153
      <entry>NIL</entry>
154
      <entry>NIL</entry>
155
      <entry>NIL</entry>
156
     </row>
157
     <row>
158
      <entry>#.(MAKE-PATHNAME :TYPE "*")</entry>
159
      <entry>NIL</entry>
160
      <entry>:WILD</entry>
161
      <entry>NIL</entry>
162
      <entry>NIL</entry>
163
     </row>
164
    </tbody>
165
   </tgroup>
166
  </table>
167
 </section>
168
169
 <section xml:id="ansi.pathnames.wild">
170
  <title>Wild pathnames and matching</title>
171
172
  <para>&ECL; accepts four kind of wildcards in pathnames.</para>
173
  <itemizedlist>
174
   <listitem>
175
    <para>A single wildcard in a directory component, file name, type or
176
    version is parsed as the <symbol>:WILD</symbol> value. See for instance
177
    <literal>"*.*"</literal>, <literal>"/home/*/.bashrc"</literal>, etc</para>
178
   </listitem>
179
   <listitem>
180
    <para>A double wildcard in a directory component, such as in
181
    <literal>"/home/**/"</literal> is parsed as the
182
    <symbol>:WILD-INFERIORS</symbol>, and matches any number of directories,
183
    even nested ones, such as: <filename>/home/</filename>,
184
    <filename>/home/jlr</filename>, <filename>/home/jlr/lib</filename>,
185
    etc.</para>
186
   </listitem>
187
   <listitem>
188
    <para>An isolated wildcard <literal>"log*.txt"</literal> matches any number
189
    of characters: <filename>log.txt</filename>,
190
    <filename>log_back.txt</filename>, etc.</para>
191
   </listitem>
192
   <listitem>
193
    <para>A question mark <literal>"log?.txt"</literal> matches a single
194
    character: <filename>log1.txt</filename>,
195
    <filename>log2.txt</filename>...</para>
196
   </listitem>
197
  </itemizedlist>
198
199
  <para>The matching rules in &CommonLisp; and &ECL; are simple but have some unintuitive consequences when compared to Unix/DOS rules. The most important one is that directories must always end with a trailing slash <literal>/</literal>, as in <literal>#p"/my/home/directory/"</literal>. Second to that, <symbol>NIL</symbol> values can only be matched by <symbol>NIL</symbol> and <symbol>:WILD</symbol>. Hence, <literal>"*"</literal> can only match files without file type. For some examples see <xref linkend="ansi.files.directory"/>.</para>
200
  </section>
201
202
 <xi:include href="ref_c_filenames.xml" xpointer="ansi.filenames.c-dict" xmlns:xi="http://www.w3.org/2001/XInclude"/>
203
204
</chapter>
205
</book>